diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..ef2210b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Force LF line endings for all text files +* text=auto eol=lf + +# Ensure shell scripts are always LF +*.sh text eol=lf diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e0b85b7..97545a5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -85,11 +85,8 @@ jobs: python -m pip install --upgrade pip pip install pyyaml - - name: Validate policy files (strict) - run: python -m azext_prototype.governance.policies.validate --dir azext_prototype/governance/policies/ --strict - - - name: Validate workload templates against policies (strict) - run: python -m azext_prototype.templates.validate --dir azext_prototype/templates/workloads/ --strict + - name: Validate governance (policies, anti-patterns, standards, workloads) + run: python -m azext_prototype.governance.validate --all --strict test: name: Test (Python ${{ matrix.python-version }}) @@ -191,6 +188,11 @@ jobs: " echo "Stamped version: $CI_VERSION" + - name: Compute policy embeddings + run: | + python -m pip install sentence-transformers + python scripts/compute_embeddings.py + - name: Inject App Insights connection string and build wheel run: | python -m pip install --upgrade pip "setuptools<70" wheel==0.30.0 diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 0282a55..a69745d 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -58,11 +58,8 @@ jobs: python -m pip install --upgrade pip pip install pyyaml - - name: Validate policy files (strict) - run: python -m azext_prototype.governance.policies.validate --dir azext_prototype/governance/policies/ --strict - - - name: Validate workload templates against policies (strict) - run: python -m azext_prototype.templates.validate --dir azext_prototype/templates/workloads/ --strict + - name: Validate governance (policies, anti-patterns, standards, workloads) + run: python -m azext_prototype.governance.validate --all --strict test: name: Test (Python ${{ matrix.python-version }}) @@ -154,6 +151,11 @@ jobs: python -m pip install --upgrade pip pip install "setuptools<70" wheel==0.30.0 + - name: Compute policy embeddings + run: | + pip install sentence-transformers + python scripts/compute_embeddings.py + - name: Inject App Insights connection string and build wheel run: | WHEEL_SRC="azext_prototype/telemetry/__init__.py" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8e149b8..4bf3ea6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -71,13 +71,10 @@ jobs: python -m pip install --upgrade pip pip install "setuptools<70" wheel==0.30.0 - - name: Validate governance policies + - name: Validate governance (policies, anti-patterns, standards, workloads) run: | pip install pyyaml - python -m azext_prototype.governance.policies.validate --dir azext_prototype/governance/policies/ --strict - - - name: Validate workload templates against policies - run: python -m azext_prototype.templates.validate --dir azext_prototype/templates/workloads/ --strict + python -m azext_prototype.governance.validate --all --strict - name: Stamp version into metadata run: | @@ -95,6 +92,11 @@ jobs: echo "Stamped version: $TAG_VERSION" echo "Preview: $(python -c "import re; print(bool(re.search(r'(a|b|rc|alpha|beta|preview|dev)\d*', '$TAG_NAME')))")" + - name: Compute policy embeddings + run: | + pip install sentence-transformers + python scripts/compute_embeddings.py + - name: Inject App Insights connection string and build wheel run: | WHEEL_SRC="azext_prototype/telemetry/__init__.py" diff --git a/.gitignore b/.gitignore index 75092e4..4ca52b2 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,9 @@ eggs/ sdist/ wheels/ +# --- Generated at build time --- +azext_prototype/governance/*.vectors.json + # --- Python bytecode --- __pycache__/ *.py[cod] diff --git a/COMMANDS.md b/COMMANDS.md index b3d3569..941222d 100644 --- a/COMMANDS.md +++ b/COMMANDS.md @@ -405,7 +405,7 @@ az prototype deploy [--stage] [--rollback-info] [--generate-scripts] [--script-type {container_app, function, webapp}] - [--script-resource-group] + [--script-rg] [--script-registry] ``` @@ -651,7 +651,7 @@ Azure deployment target type for `--generate-scripts`. | Default value: | `webapp` | | Accepted values: | `container_app`, `function`, `webapp` | -`--script-resource-group` +`--script-rg` Default resource group name for `--generate-scripts`. diff --git a/FEATURES.md b/FEATURES.md index 2523a11..68bf5f2 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -19,7 +19,7 @@ ## Multi-Agent System -- 11 built-in AI agents with specialized roles: architecture, infrastructure, application code, security, monitoring, QA, cost analysis, documentation, project management, and business analysis +- 12 built-in AI agents with specialized roles: architecture, infrastructure, application code, security, monitoring, governance, QA, cost analysis, documentation, project management, and business analysis - Three-tier agent resolution — custom agents override built-in agents, or extend the system with new roles - Formal agent contracts — declared inputs, outputs, and delegation targets for dependency validation - Parallel execution — independent agent tasks run concurrently with automatic dependency ordering diff --git a/HISTORY.rst b/HISTORY.rst index 307b506..66d0761 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -3,6 +3,893 @@ Release History =============== +0.2.1b6 ++++++++ + +Generation quality improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Simplified state management** — removed centralized + ``.terraform-state/`` directory and ``stage-N-slug.tfstate`` naming + convention. Each stage uses the default ``terraform.tfstate`` in its + own directory. Cross-stage references use simple relative paths + (``../stage-1-managed-identity/terraform.tfstate``). Removed + TFM-TF-003, STAN-TF-011, and the CRITICAL STATE FILE NAMING section + from TERRAFORM_PROMPT. Eliminates the #1 recurring QA failure. +* **Stage context in transforms** — ``apply()`` now accepts ``stage`` + dict and ``stage_content`` (all files concatenated), enabling + structured handlers to use stage metadata and cross-file reference + checking. +* **TFM-TF-001 cross-file fix** — unused remote state detection now + checks references across ALL stage files (via ``stage_content``), + not just the file containing the declaration. Prevents false removal + of remote state blocks referenced in ``locals.tf`` or ``outputs.tf``. +* **29 transform unit tests** — comprehensive tests for all 6 handlers: + load, apply filtering, capacityMode replacement, unused remote state + (single-file and cross-file), response_export_values injection, + resource group parent_id, PE removal, and stage context integration. +* **``response_export_values`` prompt strengthening** — TERRAFORM_PROMPT + changed from "add when outputs reference it" to "add to EVERY + azapi_resource, no exceptions." Violations section with rejected + examples. +* **TFM-TF-002** — structured transform that adds + ``response_export_values = ["*"]`` to azapi_resource blocks missing it. +* **TFM-NET-001** — structured transform that removes private endpoint, + DNS zone, and DNS zone group resources from non-networking stages. +* **Python knowledge** — added Common Pitfalls section: no module-level + client instantiation, no mutable default parameters for services, + ``hmac.HMAC`` not ``hmac.new``, Protocol classes for interfaces, + pinned dependency ranges. +* **React knowledge** — added Common Pitfalls section: no ``require()`` + in Vitest tests (ESM only), no dynamic ``import()`` in test bodies, + ConnectionString over InstrumentationKey, module-level MSAL mocks. + +Post-generation transforms +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **New governance type: transforms** — deterministic fixes for known AI + fabrications, applied automatically after file generation and before QA. + No AI call, no token cost. YAML-defined with ``kind: transform``, + scoped by ``targets.services`` (ARM namespaces) and ``applies_to`` + (agent names). Directory structure mirrors policies + (``governance/transforms/{category}/{service}.transform.yaml``). +* **TFM-LA-001** — moves ``disableLocalAuth`` from ``properties.features`` + to ``properties`` root on Log Analytics workspaces (ARM silently drops + it if nested wrong). +* **TFM-CDB-001** — replaces ``capacityMode = "Serverless"`` with + ``capabilities = [{ name = "EnableServerless" }]`` on Cosmos DB. +* **TFM-CDB-002** — injects ``backupPolicy.type = "Continuous"`` on + serverless Cosmos DB accounts when missing. +* **Build pipeline integration** — transforms run at three points: after + initial generation, after each QA remediation, and after re-entry + remediation. QA never sees untransformed files. +* **Governance index** — transforms indexed alongside policies, + anti-patterns, and standards for embedding-based retrieval. +* **Structured transform handlers** — transforms support ``type: structured`` + with a ``handler`` field pointing to a registered Python function for + complex multi-step fixes that regex can't handle. +* **TFM-TF-001** — removes unused ``terraform_remote_state`` data sources + and their associated ``*_state_path`` variables (structured handler). +* **Validation** — ``az prototype validate`` always validates transforms + (schema, unique IDs, required fields). + +Four-level taxonomy +~~~~~~~~~~~~~~~~~~~~ +* **Layer → Capability → Component → Resource** — consistent four-level + hierarchy across all layers. ``category`` renamed to ``capability`` on + stage dicts; ``component`` field added to service items. + ``knowledge/taxonomy.yaml`` is the canonical source of truth, validated + by ``az prototype validate``. +* **Governance ``category`` → ``domain``** — all governance YAML files + (policies, anti-patterns, standards) and templates renamed ``category`` + to ``domain`` for clarity. JSON schemas, Python loaders, and tests + updated. Governance ``domain`` classifies documents; stage ``capability`` + classifies deployment stages. + +Layer system +~~~~~~~~~~~~~ +* **Formal layer architecture** — deployment stages now carry both ``layer`` + and ``capability`` fields. Four layers define service boundaries and agent + ownership: Core (cloud-architect — identity, observability), Infrastructure + (infrastructure-architect — networking, compute, supporting services), Data + (data-architect — databases, storage, messaging), and Application + (application-architect — source code with 5 sub-layers). +* **Layer definition files** — ``knowledge/layers/`` contains authoritative + boundary docs for each layer: what belongs, what doesn't, which agents own + it, deployment order, inter-layer communication patterns, and governance + rules. +* **Layer-aware knowledge loading** — ``KnowledgeLoader.compose_context()`` + accepts a ``layer`` parameter. Layer content is injected between role and + constraints in priority order, giving agents clear boundary awareness during + generation. ``_apply_stage_knowledge()`` maps stage layers to knowledge + layer files automatically. +* **Layer inference** — ``_normalize_stages()`` derives ``layer`` from + ``category`` and stage name when the AI doesn't provide one. Identity and + monitoring stages map to Core; data/infra/app/docs map to their respective + layers. Fallback deployment plans, networking injection, and incremental + rebuild all set ``layer`` explicitly. +* **Deployment plan prompts** — Phase 1 and Phase 2 prompts now include + ``layer`` in the JSON format, examples, and instructions. The layer + reference table documents all 5 layer values and their meanings. +* **Layer info in constraints** — ``constraints.md`` Section 10 documents the + layer architecture, service placement rules, and layer-category mapping + table. + +Application sub-layers +~~~~~~~~~~~~~~~~~~~~~~~ +* **``sub_layers`` on ``AgentContract``** — developer agents now declare which + application sub-layers they can generate: ``csharp-developer`` handles API, + business-logic, data-access, background, and presentation (Blazor); + ``python-developer`` handles API, business-logic, data-access, background; + ``react-developer`` handles presentation only. +* **Architect → developer delegation** — ``_decompose_app_stage()`` detects + the language from stage name, service names, and architecture context, then + routes directly to the matching developer with sub-layer guidance injected + into the task prompt. Falls back to the application-architect when no + language can be detected. +* **Application-architect prompt rewrite** — sub-layer definitions now include + directory conventions, developer assignments, and cross-layer dependency + rules. The delegation strategy section documents how technology choices + from discovery map to developer assignments. +* **Developer prompt sub-layer organization** — C#, Python, and React + developer prompts now include sub-layer annotated project structures with + explicit rules for inter-layer dependencies (API → Business Logic → + Data Access, all via interfaces/DI). + +Code quality +~~~~~~~~~~~~~ +* **American English normalization** — renamed ``_normalise_stages()`` to + ``_normalize_stages()``, ``_categorise_service()`` to + ``_categorize_service()``, and fixed British spellings in comments across + 8 files (serialise, specialised, initialised, centralises, summarise). + +Documentation +~~~~~~~~~~~~~~ +* **Wiki — Layer-Architecture.md** — four-level taxonomy, layer ownership, + deployment order, service placement rules. +* **Wiki — Application-Architecture.md** — sub-layer structure, architect → + developer delegation, developer contracts, language detection. +* **Wiki — Agent-System.md** — updated for 20 agents with layer ownership + and contract sub_layers tables. + +Knowledge +~~~~~~~~~~ +* **Private endpoint architecture boundary** — ``constraints.md`` now + explicitly forbids creating private endpoint or DNS zone group resources + outside the dedicated Networking stage. ``terraform.md`` updated: PE + variables removed from service module template, PE pattern marked + "Networking stage only", security checklist changed from "Enable private + endpoints" to "Set publicNetworkAccess Disabled", and "Always include + private endpoint" replaced with "Do NOT create private endpoints". +* **``disableLocalAuth`` ARM property placement** — ``constraints.md`` now + documents that ``disableLocalAuth`` must be a top-level property under + ``properties``, never nested inside ``properties.features``. ARM + silently drops the property at the wrong nesting level. +* **azapi-provider.md** — new knowledge file documenting the azapi provider + configuration pattern: empty ``provider "azapi" {}`` block (subscription + from CLI context), ``deploy.sh`` must run ``az account set`` and + ``export ARM_SUBSCRIPTION_ID`` before ``terraform init``, and + ``var.subscription_id`` is for ARM resource ID construction only. + Loaded automatically alongside ``terraform`` tool knowledge. + +Build — category-aware stage generation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Clear conversation history between stages** — conversation history is + now reset before each stage generation, preventing truncated content from + prior stages bleeding into subsequent stages (e.g. Stage 18 Worker code + appearing in Stage 19 Documentation output). +* **Category-aware prompt construction** — Requirements, Previously + Generated Stages, Output Format, and Scope Boundary sections are now + tailored to the stage category (infra/app/docs). App stages no longer + receive ``terraform_remote_state``, ``deploy.sh``, or ``outputs.tf`` + instructions. Docs stages are told to generate exactly + ``architecture.md`` and ``deployment-guide.md``. +* **Category-aware governor brief** — the governor policy query now uses + category-appropriate task descriptions (``"Generate application code"`` + for app stages, ``"Generate documentation"`` for docs) instead of always + including the IaC tool name. +* **Category-aware QA context** — Terraform provider compliance rules, + service policies, API versions, and companion requirements are only + injected into QA context for IaC stages. QA task prompts now include + the stage category so QA can apply the correct checklist sections + (section 13 for app, section 14 for docs). +* **Category-aware knowledge loading** — docs stages skip knowledge + loading entirely. App stages load knowledge with ``role="developer"`` + and ``tool=None`` instead of always using the IaC tool and + ``role="infrastructure"``. +* **Framework-aware app scaffolding** — ``_get_app_scaffolding_requirements`` + now detects the language/framework from service names and stage directory + (e.g. ``api-fastapi`` → Python, ``spa-react`` → TypeScript) instead of + hardcoding C#/.NET. No language is assumed by default. +* **Stage-aware continuation prompt** — when a response is truncated + (``finish_reason=length``), the continuation prompt now includes stage + number, name, and category to keep the model on track. +* **IaC file filtering for app/docs stages** — docs stages use an + allowlist (only ``architecture.md`` and ``deployment-guide.md``). + App stages block all IaC files (``*.tf``, ``*.bicep``, ``*.bicepparam``, + ``deploy.sh``) instead of an incomplete filename blocklist. + +Build resilience +~~~~~~~~~~~~~~~~~ +* **Debug logging for layer architecture** — generation loop log points + now include ``layer``, ``capability``, ``agent_name``, and ``delegated`` + fields. Knowledge loading logs layer and service count. +* **Per-stage advisory with dedicated advisor agent** -- advisory notes + are now generated per-stage immediately after QA passes, using a new + ``advisor`` built-in agent. Phase 4 aggregates per-stage advisories + into ``ADVISORY.md`` with no AI call, eliminating the prompt-too-large + error that occurred when all generated files exceeded the 168K token + Copilot API limit. +* **``CopilotPromptTooLargeError``** -- new exception class raised when + the Copilot API rejects a prompt for exceeding its token limit. + Includes ``token_count`` and ``token_limit`` attributes for callers + to decide how to truncate. Design stage catches this and + automatically trims the architecture context before retrying. +* **Copilot API error handling cleanup** -- removed the misleading + "Ensure you have a valid GitHub Copilot Business or Enterprise license" + message from all non-200 API errors (it was a red herring for token + limit, timeout, and other failures). +* **Request ID logging** -- ``x-request-id`` response header from the + Copilot API is now captured in the debug log for every request, + enabling correlation with GitHub support. +* **Timeout retry with countdown** -- Copilot API timeouts trigger up + to 5 retry attempts with escalating wait periods (15s, 30s, 60s, 120s). + A live countdown timer shows seconds remaining before each retry, + preventing the UI from appearing to hang. Retry coverage includes + generation, QA review, and remediation calls. +* **Rate limit handling (HTTP 429)** -- ``CopilotRateLimitError`` raised + when the API returns 429. The ``Retry-After`` header value is used for + the countdown wait, falling back to the backoff schedule if missing. + Rate limit events are logged with request ID for correlation. +* **Stage completion gating** -- stages are only marked ``"generated"`` + after passing QA. New intermediate sub-states: + + - ``"generating"`` -- AI agent is producing files. If interrupted + (timeout, crash), re-entry deletes artifacts and regenerates. + - ``"validating"`` -- files on disk, awaiting QA. If QA fails after + max remediation attempts, build stops. User fixes files manually, + re-runs build, and QA re-validates without regenerating. + - ``"generated"`` -- QA passed. Terminal success state. + +* **Downstream cascade on re-validation** -- when a ``"validating"`` + stage passes QA on re-run (user fixed it), all downstream + ``"generated"`` stages are reset to ``"pending"`` so they regenerate + with updated upstream outputs. +* **QA failure output cleanup** -- when QA fails and stops the build, + only issue descriptions and fix instructions are shown. Full file + contents are no longer printed to the console. +* **Application code stages** -- Phase 1 prompt now instructs the + architect to create ``category: "app"`` stages for source code, + with explicit dependency chain documentation ensuring app stages + come after all infrastructure stages. +* **``CopilotTimeoutError``** -- new exception class (extends + ``CLIError``) enables retry logic to catch timeouts specifically + without catching other API errors. + +Benchmark suite +~~~~~~~~~~~~~~~~ +* **14-benchmark quality suite** -- project-agnostic benchmarks (B-INST + through B-ANTI) measuring instruction adherence, constraint compliance, + technical correctness, security posture, operational readiness, dependency + hygiene, scope discipline, code quality, output completeness, cross-stage + consistency, documentation quality, response reliability, RBAC + architecture, and anti-pattern absence. Each benchmark scored 0-100 with + 4-5 weighted sub-factors. +* **Benchmark report template** (``benchmarks/TEMPLATE.html``) -- reusable + HTML template with fixed rendering engine; only data arrays change between + runs. Includes per-stage dimension tables, analysis notes, systematic + strengths/weaknesses, critical bugs table, and dimension heatmap. +* **Benchmark trends dashboard** (``benchmarks/overall.html``) -- Chart.js + time-series dashboard with per-benchmark detail tabs showing sub-factor + breakdowns, scoring methodology, and improvement areas with severity. +* **PDF report generation** (``scripts/generate_pdf.py``) -- populates + ``benchmarks/TEMPLATE.docx`` with scores, generates matplotlib charts + (overall trend, 14 factor comparisons, 14 score trends), embeds all 29 + charts into the DOCX, converts to PDF via ``docx2pdf``, and cleans up + the temporary DOCX. +* **Scoring instructions** (``benchmarks/INSTRUCTIONS.md``) -- testing + methodology, extraction scripts, copy-paste analysis instructions, and + report generation rules. + +Build quality improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Tag placement root cause fix** -- constraint on line 36 of + ``terraform_agent.py`` said "in body block", directly causing tags-inside- + body across 11/14 stages. Changed to "CRITICAL: as top-level attribute". + Added dedicated ``## CRITICAL: TAGS PLACEMENT`` section with correct and + incorrect examples. +* **NEVER directive hierarchy** -- added ``## CRITICAL: DIRECTIVE HIERARCHY`` + section to ``build_session.py``. NEVER/MUST directives in policies now + explicitly override architecture context and POC notes during generation. + Users can still override post-generation via PolicyResolver. +* **deploy.sh requirements** -- replaced bullet list in ``TERRAFORM_PROMPT`` + with 13-point ``## CRITICAL: deploy.sh REQUIREMENTS`` section. Scripts + under 100 lines are rejected. Must include ``--dry-run``, ``--destroy``, + ``--help``, pre-flight validation, and post-deployment verification. +* **Scope boundary enforcement** -- added ``## CRITICAL: SCOPE BOUNDARY`` + section. Resources not listed in "Services in This Stage" and not + required by policy companions are rejected. +* **Provider hygiene** -- added ``## CRITICAL: PROVIDER RESTRICTIONS`` + section. Only ``hashicorp/azapi`` allowed; ``azurerm`` and ``random`` + providers rejected. Corresponding QA checklist updated. +* **Subnet drift prevention** -- VNET-001 policy rewritten for both + Terraform and Bicep: VNet declares only ``addressSpace``; subnets are + separate child resources. New prohibition: "NEVER define subnets inline + in the VNet body." Added ``## CRITICAL: SUBNET RESOURCES`` to + ``TERRAFORM_PROMPT``. +* **Networking stage boundary** -- expanded ``_get_networking_stage_note()`` + to explicitly prohibit PE/DNS creation in service stages when a networking + stage handles them. +* **Application code stages** -- Phase 1 deployment plan prompt now + instructs the architect to create ``category: "app"`` stages for + application source code (APIs, workers, functions, web apps, Logic Apps) + separate from ``category: "infra"`` stages that provision Azure + resources. Stage ordering now documents full dependency chain: each + group (identity, monitoring, networking, data, compute, integration, + app, docs) lists what it depends on and what it provides downstream. +* **Empty message filtering** -- ``CopilotProvider._messages_to_dicts()`` + now skips messages with empty, None, or whitespace-only content to + prevent HTTP 400 errors. ``BaseAgent.get_system_messages()`` adds + ``.strip()`` guards on governance, standards, and knowledge text. + Root cause was ``set_governor_brief(" ")`` (single space) which + created a whitespace-only system message rejected by the API. +* **RBAC principal separation** -- added Section 6.4 to ``constraints.md``: + administrative roles target deploying user, data roles target app MI. +* **Cosmos DB RBAC documentation** -- added Section 6.5 to + ``constraints.md``: data-plane roles must use ``sqlRoleAssignments``, not + ARM ``roleAssignments``. +* **azapi v2.x semantics** -- provider version injection now documents v2.x + semantics (top-level tags, ``.output.properties`` access, native HCL + body maps). +* **Documentation agent max_tokens** -- increased from 4,096 to 204,800 + (approx 350-400 pages) to prevent Stage 14 truncation. +* **Documentation agent prompt** -- enriched with context handling, + completeness requirement, and explicit instructions to reference actual + stage outputs. +* **Upstream dependency enforcement** -- task prompt and + ``TERRAFORM_PROMPT`` now explicitly state "CRITICAL: Only add + terraform_remote_state blocks for stages listed as upstream + dependencies." Prevents unnecessary dependencies (e.g., Stage 10 + referencing Stage 4 networking when it has no networking dependency). + +Governance restructuring +~~~~~~~~~~~~~~~~~~~~~~~~~ +* **Domain-prefixed policy IDs** -- all 425 policy rule IDs renamed with + domain prefixes for clarity: + + - ``AZ-`` for Azure service-specific rules (321 rules) + - ``WAF-COST-`` for cost optimization (20 rules) + - ``WAF-PERF-`` for performance (25 rules) + - ``WAF-REL-`` for reliability (20 rules) + - ``WAF-SEC-`` for security principles (16 rules) + - ``CC-INT-`` for cross-cutting integration patterns (26 rules) + +* **Well-Architected Framework alignment** -- cost, performance, + reliability, and security policies organized under WAF categories. + Integration patterns separated as cross-cutting. +* **STAN- prefixed standard IDs** -- all 38 design standard principle IDs + renamed with ``STAN-`` prefix for consistency: + + - ``STAN-DES-`` for design principles (5 principles) + - ``STAN-CODE-`` for coding standards (5 principles) + - ``STAN-PY-`` for Python application standards (5 principles) + - ``STAN-CS-`` for .NET application standards (5 principles) + - ``STAN-BCP-`` for Bicep module standards (8 principles) + - ``STAN-TF-`` for Terraform module standards (10 principles) + +* **Wiki governance subpages** -- 108 individual wiki pages (one per + service/resource), auto-generated via ``scripts/generate_wiki_governance.py`` + using templates in ``scripts/templates/``. Sidebar restructured with + grouped sections and individual subpages. +* **Developer ``applies_to`` expansion** — 340 governance rules updated + to include ``csharp-developer`` and ``python-developer`` alongside + ``app-developer``, ensuring language-specific developers receive relevant + policies. +* **Generic application standards** — ``generic.yaml`` with 5 STAN-APP + principles for the generic ``app-developer`` agent (Azure SDK auth, + project structure, configuration, health checks, structured logging). +* **Companion resource consistency** — all 778 ``companion_resources`` + entries across 72 policy files now have required ``type``, ``name``, and + ``description`` fields. String entries converted to proper dicts. JSON + schema updated to require ``name``. Policy loader simplified. +* **Duplicate rule ID consolidation** — 591 redundant rule entries across + 22 policy files consolidated into 428 unique rules with merged targets. +* **Taxonomy validation** — ``az prototype validate`` always includes + ``taxonomy.yaml`` structure validation (layer/capability/component). + +Anti-pattern detection +~~~~~~~~~~~~~~~~~~~~~~~ +* **ANTI- prefixed IDs** -- all anti-pattern checks now have explicit IDs + with ``ANTI-`` prefix: + + - ``ANTI-SEC-`` for security (6 checks) + - ``ANTI-AUTH-`` for authentication (3 checks) + - ``ANTI-NET-`` for networking (5 checks) + - ``ANTI-STOR-`` for storage (2 checks) + - ``ANTI-CONT-`` for containers (2 checks) + - ``ANTI-ENC-`` for encryption (3 checks) + - ``ANTI-MON-`` for monitoring (2 checks) + - ``ANTI-COST-`` for cost (3 checks) + - ``ANTI-COMP-`` for completeness (8 checks) + - ``ANTI-TFS-`` for Terraform structure (7 checks) + - ``ANTI-BCS-`` for Bicep structure (7 checks) + + Scanner output now includes the check ID in each warning + (e.g., ``[ANTI-SEC-001] Possible credential/secret...``). +* **New domain: ``bicep_structure``** -- 7 new anti-pattern checks for + inline resources, listKeys/listSas usage, hardcoded names, missing + @description decorators, missing outputs, deploy.sh error handling, + and outdated API versions. +* **New domain: ``terraform_structure``** -- 7 anti-pattern checks for + unused azurerm/random providers, azapi v1.x versions, non-deterministic + ``uuid()``, ``jsondecode()`` on v2.x output, and azurerm resource usage. + Total checks: 48 across 11 domains. +* **Hardcoded upstream name detection** -- new completeness check catches + ALZ-patterned hardcoded resource names (``zd-``, ``pi-``, ``pm-``, + ``pc-`` prefixes). +* **QA scope compliance** -- added Section 8 to QA engineer checklist: + scope compliance, tag placement, and azurerm resource checks. +* **Anti-pattern scan skips documentation stages** -- docs describe the + architecture (including SQL auth, public access patterns) which triggered + false positives. Scan now skips stages with ``category == "docs"``. +* **ANTI-NET-006/007** -- new checks for invalid placeholder private endpoints + pointing at VNets (ARM 400 at deploy time) and VNet/NSG diagnostic settings + using ``allLogs`` category (only ``AllMetrics`` is supported). +* **Networking stage guidance** -- ``TERRAFORM_PROMPT`` and ``BICEP_PROMPT`` + now include ``## CRITICAL: NETWORKING STAGE RULES`` preventing placeholder + PEs and wrong diagnostic categories. QA checklist updated with Section 9 + (Networking Stage) and anti-oscillation guidance. +* **Safe pattern audit** -- tightened overly broad safe patterns across all + anti-pattern domains. Removed ``"production"``, ``"development"``, + ``"identity"``, ``"least privilege"`` and other single-word patterns that + caused cross-contamination at the whole-text scan level. +* **ANTI-NET-008** -- detect diagnostic settings on NSG resources (NSGs have + no log or metric categories; ARM rejects with HTTP 400). +* **ANTI-MON-003** -- detect deprecated ``InstrumentationKey`` outputs (use + ``connection_string`` instead). +* **Private DNS zone lookup** (``knowledge/private_dns_zones.py``) -- static + mapping of ARM resource types to exact private DNS zone FQDNs, injected + into the networking stage task prompt. Eliminates DNS zone naming errors. +* **Extension resource tag guidance** -- terraform and bicep agent prompts now + explicitly prohibit ``tags`` on ``diagnosticSettings``, ``roleAssignments``, + and ``locks`` (ARM extension resources that reject tags with HTTP 400). +* **deploy.sh correctness rules** -- terraform agent prompt now documents that + ``terraform output`` has no ``-state=`` flag, and cleanup traps must use + captured ``$?`` not script-level variables. +* **Service registry normalization** -- renamed ``bicep_resource`` to + ``resource_type`` and ``bicep_api_version`` to ``api_version`` across all + 30 service entries. Removed ``terraform_resource`` (listed ``azurerm_*`` + names which are wrong for azapi). Added Cosmos DB child resources + (``sqlRoleAssignments``, ``sqlDatabases``, ``sqlContainers``). +* **Knowledge file azapi migration** -- converted 424 ``azurerm_`` references + across 25 service knowledge files to ``azapi_resource`` patterns. This was + a major source of incorrect resource patterns in generated code. +* **Container Apps identity rules** -- added to ``container-apps.md``: + UAMI required for ACR pull, no circular ``depends_on``, + ``AZURE_CLIENT_ID`` for multi-identity disambiguation. +* **New anti-patterns**: ANTI-CONT-003 (SystemAssigned-only with ACR), + ANTI-AUTH-004 (Key Vault missing Crypto User), ANTI-COMP-009 (Storage + Blob Delegator vs Data Contributor). +* **QA false positive fix** -- Section 10 (Output Consistency) no longer + flags cross-stage output keys as "non-standard" when they match the + actual exported names from upstream stages. +* **Systemic QA fixes** -- added ``SHARED_IAC_RULES`` for cross-stage dead + code prohibition (no unused remote state refs), unconditional RBAC for + worker identity, blob service diagnostic parent rule. QA Section 12 + (ARM Schema Correctness) covers Cosmos serverless, ``disableLocalAuth`` + nesting, blob diagnostics, unconditional RBAC. +* **ANTI-COMP-010** -- detect ``capacityMode = "Serverless"`` (does not + exist in Cosmos DB ARM schema; use ``capabilities`` instead). +* **ANTI-COMP-011** -- detect blob diagnostics using string interpolation + instead of explicit blob service child resource. +* **Knowledge file coverage** -- created 44 new service knowledge files + covering every Azure policy domain. Each file includes When to Use, + POC Defaults, Terraform (azapi) patterns, Bicep patterns, Common + Pitfalls, and Production Backlog sections. +* **App/docs stage guardrails** -- app stages generate application source + code only (no deploy.sh, no Terraform/Bicep). Docs stages generate + markdown only. QA and policy checks run on **all** stage categories. + IaC-specific anti-pattern scans still skip app/docs. Defense-in-depth + file blocking prevents deploy.sh and IaC files from being written for + app/docs stages even if the agent generates them. QA checklist + Section 13 (App) and Section 14 (Docs) added. +* **Container Apps knowledge** -- added Log Analytics shared key + retrieval (``data`` vs ``resource``), KEDA scaler namespace format, + no-duplicate-RBAC guidance. +* **ANTI-CONT-003 fix** -- narrowed to ``microsoft.app/containerapps`` + only; no longer fires on Static Web Apps or other resources. +* **Cosmos DB backup fix** -- serverless accounts should omit + ``backupPolicy`` entirely; corrected knowledge file. +* **Design notes stripping** -- anti-pattern scanner now strips + ``## Key Design Decisions`` sections before scanning, eliminating + all false positives from design notes that explain WHY choices were + made (e.g., mentioning ``InstrumentationKey`` or ``Blob Delegator`` + in explanatory context). +* **KEDA scaler fix** -- Container Apps knowledge file now documents + the definitive KEDA managed identity pattern: ``identity`` is a + **sibling** of ``type`` and ``metadata`` (not ``clientId`` in + metadata). Sourced from Microsoft docs. +* **ACR reference guidance** -- login server must come from upstream + stage output, not hardcoded. +* **Knowledge file resolution fix** -- deployment plan service names + (e.g., ``cosmos-account``, ``container-app-api``) now correctly + resolve to knowledge files (``cosmos-db.md``, ``container-apps.md``) + via a mapping table + fuzzy suffix stripping. Previously, knowledge + files were never loaded because names didn't match, causing the same + ARM schema errors every run. Knowledge cap raised from 12KB to 64KB. +* **IaC tool scoping** -- anti-pattern checks now support ``applies_to`` + field (domain-level or pattern-level, never both in the same file). + Bicep-structure checks only run on Bicep builds, Terraform-structure + and TF-specific completeness checks only on Terraform. Generic domains + (security, networking, etc.) run on all builds. ``scan()`` accepts + optional ``iac_tool`` parameter. +* **``az prototype validate``** -- new CLI command to validate all + governance files (policies, anti-patterns, standards, workloads). + Flags: ``--all``, ``--policies``, ``--anti-patterns``, ``--standards``, + ``--workloads``, ``--strict``. CI pipelines consolidated to a single + validation step. + +DRY refactoring +~~~~~~~~~~~~~~~~~ +* **``BaseState`` class** -- extracted shared ``__init__``, ``load()``, + ``save()``, ``_deep_merge()``, ``exists``/``state`` properties into + ``stages/base_state.py``. All 4 state managers (build, deploy, + discovery, backlog) inherit from it. Post-load hooks via + ``_post_load()`` for migrations and backfills. +* **``_apply_governance_check()``** -- extracted the duplicated 12-line + governance warning block from 6 agent ``execute()`` overrides into a + single method on ``BaseAgent``. Each agent now calls + ``return self._apply_governance_check(response, context)``. +* **AI provider shared utilities** -- moved ``_messages_to_dicts()`` and + ``_extract_tool_calls()`` from 3 provider files into ``ai/provider.py`` + as ``messages_to_dicts()`` and ``extract_tool_calls_from_openai()``. + Copilot provider uses ``filter_empty=True`` for its specific need. +* **``SessionMixin``** -- extracted shared ``_maybe_spinner()``, + ``_countdown()``, ``_setup_token_tracker()``, and + ``_setup_escalation_tracker()`` into ``stages/session_mixin.py``. + All 4 session classes (build, deploy, discovery, backlog) inherit it. +* **``safe_load_yaml()``** -- shared YAML loading helper in + ``governance/__init__.py`` replaces duplicated try/except blocks + in anti-patterns and standards loaders. + +Prompt optimization +~~~~~~~~~~~~~~~~~~~~ +* **TERRAFORM_PROMPT rewrite** -- complete rewrite with CRITICAL sections for + ``response_export_values``, state file naming convention, cross-stage + dependencies via ``terraform_remote_state``, output naming convention, + deploy.sh standardization (logging functions, control flow, auto-approve + pattern, env var convention), design notes format, diagnostic settings + pattern, provider block template, and variable validation examples. +* **BICEP_PROMPT parity** -- added file structure rules, deploy.sh + requirements (150-line minimum with argument parsing), subnet drift + prevention, diagnostic settings, design notes format, and output format + rules matching the Terraform prompt. +* **APP_DEVELOPER_PROMPT enrichment** -- added Azure service connection + patterns (Cosmos DB, Storage, Key Vault, Service Bus with + DefaultAzureCredential), deploy.sh requirements (container build/push, + health check, rollback), and project structure template. +* **Prior stage output key injection** -- downstream stages now see exact + output key names from previously generated stages, eliminating output + name mismatches. +* **RBAC enforcement language** -- companion requirements now explicitly + require ALL listed roles in the current stage with no deferral. +* **Policy agent name fix** -- ``_resolve_service_policies()`` uses actual + IaC tool agent name instead of hardcoded ``"terraform-agent"``. +* **Advisory notes to file** -- advisory review output saved to + ``concept/docs/ADVISORY.md`` instead of printing to screen. +* **QA checklist expansion** -- added checks for ``response_export_values``, + empty files, ``required_version``, state file naming, output key naming + consistency, and remote state path matching. +* **Anti-pattern expansion** -- 40 checks across 10 domains (was 39). + Added ``.output.properties`` without ``response_export_values`` detection + and data-plane role name safe_patterns for spurious warning prevention. +* **Documentation agent** -- added exact directory path guidance, actual + SKU value guidance, and mandatory deployment guide section list. +* **deploy.sh single-dash ``-auto-approve``** -- Terraform uses single + dash ``-auto-approve`` not double dash. Fixed in the deploy.sh + template. +* **Storage container API version** -- added ``blobServices/containers`` + child resource entry to service registry with verified ``@2023-05-01`` + version. ``resource_metadata.py`` now checks parent service + ``child_resources`` entries before falling through to Microsoft Learn + runtime lookup. + +Truncation recovery +~~~~~~~~~~~~~~~~~~~~ +* **Continuation now carries conversation history** -- + ``_execute_with_continuation()`` appends the truncated response as an + assistant message to ``conversation_history`` before requesting a + continuation. Previously the model had no context of what it already + generated, causing it to respond with "I don't have previous context" + instead of continuing where it left off. +* **Documentation path fix** -- removed ``docs/`` prefix from code block + labels in ``DOCUMENTATION_PROMPT``. The stage directory already + provides ``concept/docs/``, so labeling files as ``docs/architecture.md`` + produced a nested ``concept/docs/docs/architecture.md`` path. +* **Documentation stage context enrichment** -- new + ``_build_docs_context()`` reads actual ``outputs.tf`` from each + previously generated stage and injects output names, descriptions, and + file lists into the documentation prompt. This ensures docs reflect + real build artifacts (including QA remediation changes) rather than + just the planned architecture. + +AI provider +~~~~~~~~~~~~ +* **Copilot default timeout** increased from 480s to 600s (10 minutes) + to accommodate large QA remediation prompts (200KB+). + +Discovery session +~~~~~~~~~~~~~~~~~~~ +* **Unified discovery tracking (``TrackedItem``)** — consolidated three + independent tracking systems (``topics``, ``open_items``, + ``confirmed_items``) into a single ``items`` list of ``TrackedItem`` + objects. Each item carries a ``kind`` (``"topic"`` or ``"decision"``) + and a ``status`` (``"pending"``, ``"answered"``, ``"confirmed"``, + ``"skipped"``). Legacy state files are automatically migrated on load. +* **Immutable discovery topics across re-runs** — topics are established + once, persisted to ``discovery.yaml``, and immutable. Re-running + ``az prototype design`` resumes at the first unanswered topic. New + artifacts can only *add* topics, never replace existing ones. +* **Artifact inventory with content hashing** — ``discovery.yaml`` tracks + SHA-256 hashes for every artifact file and the ``--context`` string. + Re-runs only read/analyze new or changed files; unchanged content is + skipped entirely. +* **``--context`` records decisions and exits cleanly** — simple directives + (e.g. "change app name to X") are recorded as confirmed decisions and + the session exits immediately. Decision items (``kind="decision"``) are + no longer walked interactively — only ``kind="topic"`` items require input. +* **``--reset`` now clears discovery state** — clears topics, conversation + history, artifact inventory, and all structured fields. +* **``###`` subsections folded into parent topics** — only ``##`` (level-2) + headings become discovery topics. Level-3 subsections are included in + their parent topic's content. The biz-analyst prompt explicitly prohibits + ``###`` headings. + +Slash commands +~~~~~~~~~~~~~~~ +* **Slash commands no longer consume topic iterations** — the inner + follow-up loop (max 5 per topic) only counts real AI exchanges. + Slash commands and empty inputs do not advance the counter. +* **Improved ``/why`` output** — snippets increased from 150 to 500 chars; + each exchange shows which discovery topic was being discussed. +* **``/restart`` breaks out of section loop** — previously reset state but + left the session iterating stale topics. + +Governor agent +~~~~~~~~~~~~~~~ +* **Governor agent — embedding-based policy enforcement** — new built-in + agent (``governor``) that replaces injecting all 13 policy files (~40KB) + into every agent's system prompt. Three modes: ``brief()`` retrieves the + top-K most relevant rules (~1-2KB); ``review()`` evaluates output against + the full policy set using parallel chunked AI calls (``max_workers=2``). + **Wired into the build session** — before each stage's agent generates + code, the governor produces a policy brief for the specific stage context + (e.g. "generate terraform for Foundation: managed-identity, log-analytics") + and injects it via ``set_governor_brief()``. This ensures generated code + is policy-compliant from the start rather than relying solely on post- + generation QA to catch violations. The brief is also injected directly + into the task prompt as a ``## MANDATORY GOVERNANCE RULES`` section near + the end (where models pay the most attention), not just in system messages + where it was drowned out in 600KB+ prompts. Policy requirements like private endpoints and network isolation are + enforced through governance policies, not hardcoded as agent constraints. +* **One-time architecture condensation** — the full architecture document + (542KB in real projects) is condensed into per-stage context summaries + (~1KB each) via a single AI call after plan derivation. Each generation + call then uses only the condensed context + governor brief + task + instructions (~14KB total instead of 622KB). The governance brief is + now ~11% of the prompt (vs 0.24% previously), a 46x visibility increase. + Knowledge docs and standards are stripped from generation calls to keep + prompts focused. +* **Governance-reinforced QA remediation** — max attempts increased to 3 + with escalating severity. Each remediation attempt uses condensed context + and re-applies the governor brief. Severity escalates from "MUST fix" + to "CRITICAL" to "FINAL ATTEMPT — build will be rejected permanently." +* **Governor brief includes rationale and anti-patterns** — MUST rules + include implementation rationale. ALL anti-pattern violation patterns + (33 checks across 9 domains) are appended as ``NEVER GENERATE`` + directives, loaded directly from governance YAML files with zero + hardcoded logic. +* **NET-001 updated** — now explicitly requires disabling public network + access AND using private endpoints (previously only mentioned endpoints). +* **NET-005 added** — requires ``publicNetworkAccess = Disabled`` in both + Terraform and Bicep. Covers the gap where Azure defaults to Enabled. +* **Anti-pattern safe_patterns** — networking anti-pattern now exempts + ``public_network_access_enabled = false`` and + ``publicnetworkaccess = "disabled"`` to avoid false positives. + Agents receive focused policy briefs via ``set_governor_brief()``. +* **Pre-computed neural embeddings** — built-in policy embeddings are + generated at build time (``scripts/compute_embeddings.py``) using + ``sentence-transformers`` (``all-MiniLM-L6-v2``) and shipped inside the + wheel as ``policy_vectors.json``. No ``torch`` needed at runtime — works + on all platforms including Azure CLI's 32-bit Windows Python. Custom + policies use TF-IDF; non-Windows users can install + ``sentence-transformers`` for neural custom-policy embeddings. +* **New ``AgentCapability.GOVERNANCE``** enum value. Built-in agent count: + 11 → 12. + +AI provider & telemetry +~~~~~~~~~~~~~~~~~~~~~~~~ +* **Copilot default timeout** increased from 300s to 480s. +* **Lightweight AI call for ``--context`` re-entry** — topic classification + uses a ~0.5KB prompt instead of the full ~69KB governance/template stack. +* **PRU tracking for Copilot users** — status bar shows Premium Request + Units computed locally from the official multiplier table (e.g. Claude + Sonnet 4 = 1, Haiku 4.5 = 0.33, Opus 4.5 = 3). Non-Copilot providers + are unaffected. + +TUI & UX +~~~~~~~~~ +* **Build and deploy now launch TUI** — ``az prototype build`` and + ``az prototype deploy`` route through the TUI (``PrototypeApp``) for + interactive sessions, matching the design stage. Dry-run, ``--json``, + single-stage deploy, and non-interactive contexts use the legacy path. + Stage kwargs (``--reset``, ``--scope``, etc.) are passed through to + the stage execution. +* **Downstream stages marked pending on re-run** — re-running an earlier + stage (e.g. design after build+deploy) now marks all downstream stages + as pending in the TUI tree, reflecting that they depend on the changed + output and will need to be re-run. +* **Token status auto-updates after every AI call** — ``TokenTracker`` now + fires an ``_on_update`` callback after each ``record()`` call. All four + sessions (discovery, build, deploy, backlog) wire this to the console or + TUI adapter so the bottom-right status bar updates continuously. + During AI calls, a live elapsed timer ticks in the status bar + (e.g. "Analyzing architecture... (5s)") so the user knows the + extension is working, then switches to token counts after the + response arrives. +* **TUI quit shortcut** changed from Ctrl+C to Ctrl+Q. +* **Discovery UX** — clear call-to-action after AI response; trailing + colons stripped from topic headings in the stage tree. + +Debug logging +~~~~~~~~~~~~~~ +* **Exhaustive debug logging (``DEBUG_PROTOTYPE=true``)** — creates a + timestamped ``debug_YYYYMMDDHHMMSS.log`` in the project directory. + Logs full AI call payloads (system message sizes, user content, response + content, token counts, timing), every state mutation, every decision + branch, every slash command, and full error tracebacks. + +Governance policies (comprehensive overhaul) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* **90 governance policies, 428 rules** — up from 13 policies / 65 rules. + Every policy now includes exact ``terraform_pattern`` (azapi) and + ``bicep_pattern`` code, ``companion_resources`` with full IaC code, + and ``prohibitions`` listing what agents must never generate. +* **67 Azure service policies** across 11 subcategories: ai (5), compute (6), + data (16), identity (2), management (4), messaging (2), monitoring (3), + networking (17), security (4), storage (1), web (7). Updated with + WAF service guide recommendations (40 new rules across 10 services). +* **4 security policies** rewritten: authentication (5 rules), data + protection (7 rules), managed identity (6 rules), network isolation + (8 rules). Aligned with Azure Well-Architected Framework Security + pillar (SE-01 through SE-05). +* **6 integration policies**: APIM↔Container Apps (rewritten, 6 rules), + event-driven (5 rules), data-pipeline (4 rules), microservices + (5 rules), api-patterns (4 rules), frontend-backend (4 rules). +* **4 cost policies** (new): SKU selection, scaling, resource lifecycle, + reserved instances. Aligned with WAF Cost Optimization pillar. +* **5 performance policies** (new): caching, database optimization, + compute optimization, networking optimization, monitoring/observability. + Aligned with WAF Performance Efficiency pillar. +* **4 reliability policies** (new): high availability, backup/recovery, + fault tolerance, deployment safety. Aligned with WAF Reliability + pillar (RE-01 through RE-05). +* **Exact service matching with relevance filtering** — + ``PolicyEngine.resolve_for_stage()`` uses exact service name matching + (not embedding similarity). Cross-cutting policies (3+ services) are + only included when at least half their services overlap with the stage, + preventing prompt bloat from irrelevant patterns. IaC-tool filtering + strips Bicep patterns for Terraform builds and vice versa. +* **Deterministic prompt injection** — ``_resolve_service_policies()`` + injects matched policies into both generation and QA prompts as + ``## MANDATORY RESOURCE POLICIES`` with exact code templates. + +Build session +~~~~~~~~~~~~~~ +* **Two-phase deployment plan derivation** — Phase 1: the architect + produces a simple map of stages and services (no SKUs, no naming, + no governance needed). Phase 2: given the map, the architect fills + in computed names, resource types, and SKUs with ALL relevant + governance policies injected (since the service list is now known). + Eliminates SKU conflicts (e.g. Basic ACR when policy requires + Premium). +* **Service policies injected early in prompt** — ``MANDATORY RESOURCE + POLICIES`` section moved from position 13 (near end) to position 3 + (right after services list). Ensures the AI reads the exact code + templates with correct property values before it starts generating. +* **Enforce ``concept/`` output directory** — ``_normalize_stages()`` + detects when the AI uses the project name as root and fixes it. +* **``--reset`` cleans non-concept output dirs** — loads build state + before reset to find and clean project-named directories. +* **Pre-fetched API versions per resource type** — resolves correct + API version from service-registry.yaml (fast) or Microsoft Learn + (fallback) before generation. +* **Companion resource requirements** — RBAC roles, role GUIDs, and + auth method injected per-service from the service registry. +* **Truncation recovery** — ``_execute_with_continuation()`` detects + ``finish_reason == "length"`` and auto-continues (4 call sites). +* **``_max_tokens`` raised to 102,400** — Terraform, Bicep, App + Developer, and QA agents. +* **QA reviews full file content** — no per-file or total size caps. +* **Mandatory stage ordering** — Foundation=1, Networking=2 enforced + in architect prompt and ``_ensure_private_endpoint_stage()``. +* **Networking stage auto-injection** — when services need private + endpoints, a networking stage with VNet + all PEs is injected at + position 2 after Foundation. +* **Full QA report on max remediation** — when QA exhausts all + remediation attempts, the full remaining issues report is printed + (was truncated to 200 chars). +* **Full diagnostic logging** — task prompts log the FULL prompt + sent to the AI (``task_full``), the FULL response (``content_full``), + resolved service policies (``policy_full``), anti-pattern violations + detected before the policy resolver, ``max_tokens`` sent per request, + and ``finish_reason`` on every response. +* **TUI Ctrl+Q cancellation** — ``print_fn``, ``response_fn``, and + ``status_fn`` now raise ``ShutdownRequested`` when the shutdown flag + is set, breaking the worker thread out of QA/remediation loops + immediately after the current HTTP call completes. Previously the + TUI exited but the prompt hung until the full QA loop finished. + +QA agent +~~~~~~~~~ +* **QA receives service policies + API versions** — same deterministic + briefs injected into generation are also sent to QA for verification. +* **Provider compliance** (Terraform only) — no ``azurerm_*`` resources. + Scoped to Terraform builds only — Bicep builds never see azurerm + constraints. +* **Three-tier issue detection** — ``VERDICT: PASS/FAIL`` (handles + markdown bold), pass phrases, keyword fallback. Eliminates false + positives from QA responses containing "critical" in headings. +* **VERDICT instruction in QA prompt** — QA must end every review + with ``VERDICT: PASS`` or ``VERDICT: FAIL``. WARNING-only results + use PASS. Without this, QA never emitted verdicts and the keyword + fallback caused unnecessary remediation cycles. +* **Checklist items 8 + 9** — Provider Compliance and API Version + Compliance added to Mandatory Review Checklist. +* **Credential false positive fix** — ``connectionstring`` safe patterns + now include ARM property references and instrumentation context. + +Terraform agent +~~~~~~~~~~~~~~~~ +* **RBAC role assignment names** — ``random_uuid`` resource from + ``hashicorp/random`` provider. ``guid()`` does not exist in HCL. +* **publicNetworkAccess** — "ALWAYS set Disabled, networking stage + handles private endpoints." + +Security reviewer agent +~~~~~~~~~~~~~~~~~~~~~~~~ +* **Public endpoints are blockers** — unless the user explicitly + overrides, public endpoints and missing VNET are now BLOCKERs in + all environments (was WARNINGs for POC). + +Knowledge base +~~~~~~~~~~~~~~~ +* **Eliminated public access contradictions** — removed all "POC + relaxation" language from ``constraints.md``, service knowledge + files, and agent prompts that told the AI public endpoints were + acceptable for POC. Private endpoints and VNET integration are + now the default for all environments unless the user explicitly + overrides via discovery directives or custom policies. +* **Fixed 9 service knowledge files** — ``public_network_access_enabled`` + changed from ``true`` to ``false`` in Terraform examples; Bicep + examples changed from ``'Enabled'`` to ``'Disabled'``; POC Defaults + tables changed from "Enabled (POC)" to "Disabled (unless user + overrides)". +* **Copilot model catalogue** — added ``claude-sonnet-4-6`` to the + fallback model list. + +Build & CI/CD +~~~~~~~~~~~~~~ +* Build scripts (``build.sh``, ``build.bat``) and all CI/CD workflows + (``ci.yml``, ``pr.yml``, ``release.yml``) compute policy embeddings + before wheel construction. +* New policy subdirectories (azure/*, cost, performance, reliability) + have ``__init__.py`` files for proper package discovery. +* Renamed ``--script-resource-group`` deploy flag to ``--script-rg``. + +Cleanup +~~~~~~~~ +* Removed vestigial ``_SECTION_COMPLETE_MARKER`` (defined but never used). +* Removed dead code: ``build_incremental_update_prompt()``, ``items_by_kind()``. + 0.2.1b5 +++++++ diff --git a/MODELS.md b/MODELS.md index 0b7ffc8..612fe78 100644 --- a/MODELS.md +++ b/MODELS.md @@ -250,7 +250,7 @@ az prototype config show | `Invalid Azure OpenAI endpoint` | Endpoint must match `https://.openai.azure.com/`. Public OpenAI endpoints are blocked. | | Slow responses | Try a smaller/faster model like `gpt-4o-mini`. The `copilot` provider uses direct HTTP (no SDK overhead). | | Token limit exceeded | Switch to a model with a larger context window (`gpt-4.1`, `gemini-2.5-pro`). | -| Timeout on large prompts | Increase the timeout: `set COPILOT_TIMEOUT=300` (default is 300 seconds). | +| Timeout on large prompts | Increase the timeout: `set COPILOT_TIMEOUT=600` (default is 480 seconds). | --- diff --git a/README.md b/README.md index 0c918c1..6160eb4 100644 --- a/README.md +++ b/README.md @@ -67,21 +67,29 @@ View the [command reference](./COMMANDS.md) to see the full list of commands and ## Agent System ### Built-in Agents -Ships with 11 pre-defined agents: +Ships with 19 pre-defined agents: | Agent | Capability | Description | |-------|-----------|-------------| -| `cloud-architect` | Architecture | Cross-service coordination and architecture design | -| `terraform-agent` | Terraform | Terraform IaC generation | +| `cloud-architect` | Architecture | Overall overseer, Core layer ownership, deployment planning | +| `infrastructure-architect` | Infrastructure | Infrastructure layer ownership, directs terraform/bicep agents | +| `data-architect` | Data | Data layer ownership, schema and access patterns | +| `application-architect` | Application | Application layer ownership, developer delegation | +| `security-architect` | Security | Cross-cutting security, RBAC, identity, encryption | +| `terraform-agent` | Terraform | Terraform IaC generation (azapi provider) | | `bicep-agent` | Bicep | Bicep template generation | -| `app-developer` | Development | Application code generation (APIs, Functions, containers) | +| `csharp-developer` | C# / .NET | C# application code generation | +| `python-developer` | Python | Python application code generation | +| `react-developer` | React / TypeScript | React frontend code generation | +| `app-developer` | Development | Generic fallback for unsupported languages | | `doc-agent` | Documentation | Project and deployment documentation | -| `qa-engineer` | QA / Analysis | Error diagnosis from logs, strings, or screenshots; fix coordination | +| `qa-engineer` | QA / Analysis | Error diagnosis, code review, remediation | | `biz-analyst` | Business Analysis | Requirements gap analysis and interactive design dialogue | | `cost-analyst` | Cost Analysis | Azure cost estimation at S/M/L t-shirt sizes | | `project-manager` | Coordination | Scope management, task assignment, escalation | -| `security-reviewer` | Security | Pre-deployment IaC security scanning | | `monitoring-agent` | Monitoring | Observability configuration generation | +| `governor` | Governance | Embedding-based policy retrieval and enforcement | +| `advisor` | Advisory | Per-stage trade-off and risk analysis | ### Custom Agents Add your own agents via YAML or Python: diff --git a/azext_prototype/_params.py b/azext_prototype/_params.py index d52d7bf..1a9dab7 100644 --- a/azext_prototype/_params.py +++ b/azext_prototype/_params.py @@ -224,6 +224,51 @@ def load_arguments(self, _): default=False, ) + # --- az prototype validate --- + with self.argument_context("prototype validate") as c: + c.argument( + "all_areas", + options_list=["--all"], + help="Validate policies, anti-patterns, and standards.", + action="store_true", + default=False, + ) + c.argument( + "policies", + options_list=["--policies"], + help="Validate policy files.", + action="store_true", + default=False, + ) + c.argument( + "anti_patterns", + options_list=["--anti-patterns"], + help="Validate anti-pattern files.", + action="store_true", + default=False, + ) + c.argument( + "standards", + options_list=["--standards"], + help="Validate standards files.", + action="store_true", + default=False, + ) + c.argument( + "workloads", + options_list=["--workloads"], + help="Validate workload templates against policies.", + action="store_true", + default=False, + ) + c.argument( + "strict", + options_list=["--strict"], + help="Treat warnings as errors.", + action="store_true", + default=False, + ) + # --- az prototype analyze --- with self.argument_context("prototype analyze error") as c: c.argument( diff --git a/azext_prototype/agents/base.py b/azext_prototype/agents/base.py index 262755e..f6dddba 100644 --- a/azext_prototype/agents/base.py +++ b/azext_prototype/agents/base.py @@ -17,7 +17,14 @@ class AgentCapability(str, Enum): """Capabilities an agent can declare.""" ARCHITECT = "architect" + INFRASTRUCTURE_ARCHITECT = "infrastructure_architect" + DATA_ARCHITECT = "data_architect" + APPLICATION_ARCHITECT = "application_architect" + SECURITY_ARCHITECT = "security_architect" DEVELOP = "develop" + DEVELOP_CSHARP = "develop_csharp" + DEVELOP_PYTHON = "develop_python" + DEVELOP_REACT = "develop_react" TERRAFORM = "terraform" BICEP = "bicep" ANALYZE = "analyze" @@ -31,6 +38,8 @@ class AgentCapability(str, Enum): BACKLOG_GENERATION = "backlog_generation" SECURITY_REVIEW = "security_review" MONITORING = "monitoring" + GOVERNANCE = "governance" + ADVISORY = "advisory" @dataclass @@ -46,11 +55,16 @@ class AgentContract: Missing inputs are warnings (agent may still run with reduced context). outputs: Artifact keys this agent produces (added to ``AgentContext.artifacts``). delegates_to: Agent names this agent may delegate sub-tasks to. + sub_layers: Application sub-layers this agent can generate code for. + Valid values: ``presentation``, ``api``, ``business-logic``, + ``data-access``, ``background``. Empty list means the agent + does not participate in sub-layer delegation. """ inputs: list[str] = field(default_factory=list) outputs: list[str] = field(default_factory=list) delegates_to: list[str] = field(default_factory=list) + sub_layers: list[str] = field(default_factory=list) @dataclass @@ -187,21 +201,7 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: if self._enable_web_search and self._SEARCH_PATTERN.search(response.content): response = self._resolve_searches(response, messages, context) - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - # Append warnings as a note in the response - warning_block = "\n\n---\n" "**Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + warning_block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - - return response + return self._apply_governance_check(response, context) def can_handle(self, task_description: str) -> float: """Score how well this agent can handle a task (0.0 to 1.0). @@ -247,29 +247,40 @@ def get_system_messages(self) -> list[AIMessage]: # Inject governance context if self._governance_aware: governance_text = self._get_governance_text() - if governance_text: + if governance_text and governance_text.strip(): messages.append(AIMessage(role="system", content=governance_text)) # Inject design standards if self._include_standards: standards_text = self._get_standards_text() - if standards_text: + if standards_text and standards_text.strip(): messages.append(AIMessage(role="system", content=standards_text)) # Inject knowledge context if self._knowledge_role or self._knowledge_tools or self._knowledge_languages: knowledge_text = self._get_knowledge_text() - if knowledge_text: + if knowledge_text and knowledge_text.strip(): messages.append(AIMessage(role="system", content=knowledge_text)) return messages - def validate_response(self, response_text: str) -> list[str]: + def validate_response( + self, + response_text: str, + iac_tool: str | None = None, + services: list[str] | None = None, + ) -> list[str]: """Check AI output for obvious governance violations. Returns a list of warning strings (empty = clean). Called automatically by the default ``execute()`` implementation. Subclasses with custom ``execute()`` should call this too. + + Parameters + ---------- + services: + ARM resource type namespaces for the current stage. + Filters anti-pattern checks by ``targets.services``. """ if not self._governance_aware: return [] @@ -277,12 +288,50 @@ def validate_response(self, response_text: str) -> list[str]: from azext_prototype.agents.governance import GovernanceContext ctx = GovernanceContext() - return ctx.check_response_for_violations(self.name, response_text) + return ctx.check_response_for_violations(self.name, response_text, iac_tool=iac_tool, services=services) except Exception: # pragma: no cover — never let validation break the agent return [] + def _apply_governance_check(self, response: AIResponse, context: AgentContext) -> AIResponse: + """Post-response governance check. Appends warnings if found. + + Call this at the end of custom ``execute()`` overrides to + avoid duplicating the governance warning block. + """ + iac_tool = context.project_config.get("project", {}).get("iac_tool") if context.project_config else None + warnings = self.validate_response(response.content, iac_tool=iac_tool, services=None) + if warnings: + for w in warnings: + logger.warning("Governance: %s", w) + warning_block = "\n\n---\n**Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) + return AIResponse( + content=response.content + warning_block, + model=response.model, + usage=response.usage, + finish_reason=response.finish_reason, + ) + return response + + def set_governor_brief(self, brief_text: str) -> None: + """Set a governor-produced policy brief for this agent. + + When set, ``get_system_messages()`` uses this concise brief + (~1-2KB) instead of the full governance text (~40KB+). + Call with an empty string to revert to full governance. + """ + self._governor_brief = brief_text + def _get_governance_text(self) -> str: - """Return formatted governance text for system messages.""" + """Return formatted governance text for system messages. + + If a governor brief has been set via ``set_governor_brief()``, + returns that instead of the full policy/template dump. + """ + # Prefer governor brief if available + brief = getattr(self, "_governor_brief", "") + if brief: + return brief + try: from azext_prototype.agents.governance import GovernanceContext @@ -303,13 +352,24 @@ def _get_standards_text(self) -> str: except Exception: # pragma: no cover — never let standards break the agent return "" + def set_knowledge_override(self, text: str) -> None: + """Set stage-specific knowledge to replace the generic composition. + + When set, ``_get_knowledge_text()`` returns this text instead of + composing from ``_knowledge_role`` / ``_knowledge_tools``. + Call with an empty string to revert to default composition. + """ + self._knowledge_override = text + def _get_knowledge_text(self) -> str: """Return composed knowledge context for system messages. - Uses ``_knowledge_role``, ``_knowledge_tools``, and - ``_knowledge_languages`` to compose context from the knowledge - directory via :class:`KnowledgeLoader`. + If a knowledge override has been set via ``set_knowledge_override()``, + returns that instead of composing from role/tool/language declarations. """ + override = getattr(self, "_knowledge_override", "") + if override: + return override try: from azext_prototype.knowledge import KnowledgeLoader diff --git a/azext_prototype/agents/builtin/__init__.py b/azext_prototype/agents/builtin/__init__.py index faf3d96..db2c8eb 100644 --- a/azext_prototype/agents/builtin/__init__.py +++ b/azext_prototype/agents/builtin/__init__.py @@ -1,33 +1,57 @@ -"""Built-in agents that ship with the extension.""" - -from azext_prototype.agents.builtin.app_developer import AppDeveloperAgent -from azext_prototype.agents.builtin.bicep_agent import BicepAgent -from azext_prototype.agents.builtin.biz_analyst import BizAnalystAgent -from azext_prototype.agents.builtin.cloud_architect import CloudArchitectAgent -from azext_prototype.agents.builtin.cost_analyst import CostAnalystAgent -from azext_prototype.agents.builtin.doc_agent import DocumentationAgent -from azext_prototype.agents.builtin.monitoring_agent import MonitoringAgent -from azext_prototype.agents.builtin.project_manager import ProjectManagerAgent -from azext_prototype.agents.builtin.qa_engineer import QAEngineerAgent -from azext_prototype.agents.builtin.security_reviewer import SecurityReviewerAgent -from azext_prototype.agents.builtin.terraform_agent import TerraformAgent - -ALL_BUILTIN_AGENTS = [ - CloudArchitectAgent, - TerraformAgent, - BicepAgent, - AppDeveloperAgent, - DocumentationAgent, - QAEngineerAgent, - BizAnalystAgent, - CostAnalystAgent, - ProjectManagerAgent, - SecurityReviewerAgent, - MonitoringAgent, -] - - -def register_all_builtin(registry): - """Register all built-in agents into the registry.""" - for agent_cls in ALL_BUILTIN_AGENTS: - registry.register_builtin(agent_cls()) +"""Built-in agents that ship with the extension.""" + +from azext_prototype.agents.builtin.advisor import AdvisorAgent +from azext_prototype.agents.builtin.app_developer import AppDeveloperAgent +from azext_prototype.agents.builtin.application_architect import ( + ApplicationArchitectAgent, +) +from azext_prototype.agents.builtin.bicep_agent import BicepAgent +from azext_prototype.agents.builtin.biz_analyst import BizAnalystAgent +from azext_prototype.agents.builtin.cloud_architect import CloudArchitectAgent +from azext_prototype.agents.builtin.cost_analyst import CostAnalystAgent +from azext_prototype.agents.builtin.csharp_developer import CSharpDeveloperAgent +from azext_prototype.agents.builtin.data_architect import DataArchitectAgent +from azext_prototype.agents.builtin.doc_agent import DocumentationAgent +from azext_prototype.agents.builtin.governor_agent import GovernorAgent +from azext_prototype.agents.builtin.infrastructure_architect import ( + InfrastructureArchitectAgent, +) +from azext_prototype.agents.builtin.monitoring_agent import MonitoringAgent +from azext_prototype.agents.builtin.project_manager import ProjectManagerAgent +from azext_prototype.agents.builtin.python_developer import PythonDeveloperAgent +from azext_prototype.agents.builtin.qa_engineer import QAEngineerAgent +from azext_prototype.agents.builtin.react_developer import ReactDeveloperAgent +from azext_prototype.agents.builtin.security_architect import SecurityArchitectAgent +from azext_prototype.agents.builtin.terraform_agent import TerraformAgent + +ALL_BUILTIN_AGENTS = [ + # Architects + CloudArchitectAgent, + InfrastructureArchitectAgent, + DataArchitectAgent, + ApplicationArchitectAgent, + SecurityArchitectAgent, + # IaC agents + TerraformAgent, + BicepAgent, + # Language-specific developers + CSharpDeveloperAgent, + PythonDeveloperAgent, + ReactDeveloperAgent, + AppDeveloperAgent, # Generic fallback for unsupported languages (Java, Go, Rust, etc.) + # Supporting agents + DocumentationAgent, + QAEngineerAgent, + BizAnalystAgent, + CostAnalystAgent, + ProjectManagerAgent, + MonitoringAgent, + GovernorAgent, + AdvisorAgent, +] + + +def register_all_builtin(registry): + """Register all built-in agents into the registry.""" + for agent_cls in ALL_BUILTIN_AGENTS: + registry.register_builtin(agent_cls()) diff --git a/azext_prototype/agents/builtin/advisor.py b/azext_prototype/agents/builtin/advisor.py new file mode 100644 index 0000000..4b7ad84 --- /dev/null +++ b/azext_prototype/agents/builtin/advisor.py @@ -0,0 +1,95 @@ +"""Advisor built-in agent — per-stage trade-off and risk analysis. + +Generates advisory notes for each build stage, covering known +limitations, security considerations, scalability notes, cost +implications, architectural trade-offs, and missing production +concerns. Advisory notes are informational — they do not block +the build or request code changes. +""" + +from azext_prototype.agents.base import AgentCapability, AgentContract, BaseAgent + + +class AdvisorAgent(BaseAgent): + """Generate advisory notes for build stages.""" + + _temperature = 0.3 + _max_tokens = 4096 + _include_standards = True + _include_templates = False + _keywords = [ + "advisory", + "trade-off", + "limitation", + "consideration", + "risk", + "scalability", + "production", + "readiness", + ] + _keyword_weight = 0.05 + _contract = AgentContract( + inputs=["iac_code"], + outputs=["advisory_notes"], + delegates_to=[], + ) + + def __init__(self): + super().__init__( + name="advisor", + description=( + "Analyze generated infrastructure and application code to " + "produce advisory notes on trade-offs, risks, and production " + "readiness considerations" + ), + capabilities=[AgentCapability.ADVISORY], + constraints=[ + "Never suggest code changes — advisory notes are informational only", + "Focus on trade-offs, not bugs (QA already validated correctness)", + "Be concise — each advisory should be 1-2 sentences", + "Prioritize actionable items the user should be aware of", + ], + system_prompt=ADVISOR_PROMPT, + ) + + +ADVISOR_PROMPT = """You are an Azure architecture advisor. + +Your job is to review infrastructure and application code that has ALREADY +passed QA validation. You do NOT check for bugs or correctness — that work +is done. Instead, you provide concise advisory notes about trade-offs and +production readiness. + +## Focus Areas + +1. **Known Limitations** — Services with capability gaps at the chosen SKU + (e.g., Basic App Service has no staging slots, no custom domains with SSL) +2. **Security Considerations** — Default configurations that may need + hardening for production (e.g., no WAF, no DDoS protection, TLS 1.2 + but not 1.3) +3. **Scalability Notes** — Services that will need upgrading for production + load (e.g., Basic-tier databases, single-instance deployments) +4. **Cost Implications** — Potential cost surprises (e.g., egress charges, + cross-region data transfer, premium feature lock-in) +5. **Architectural Trade-offs** — Simplifications made for prototype speed + that should be revisited (e.g., single-region, no DR, shared resource + groups) +6. **Missing Production Concerns** — Gaps that are acceptable for POC but + required for production (e.g., backup policies, monitoring alerts, + incident runbooks) + +## Output Format + +Return a markdown list of advisories. Each item has a bold category tag +and a concise description: + +- **[Scalability]** App Service Basic tier limits to 3 instances max; + upgrade to Standard for auto-scale. +- **[Security]** Key Vault has no private endpoint; data-plane operations + traverse the public internet. +- **[Cost]** Cosmos DB with 400 RU/s is ~$24/mo but scales linearly; + monitor RU consumption. + +Keep the list to 5-10 items. Prioritize items the user is most likely +to overlook. Do NOT repeat items that the code already handles correctly. +""" diff --git a/azext_prototype/agents/builtin/app_developer.py b/azext_prototype/agents/builtin/app_developer.py index efd857b..22becaa 100644 --- a/azext_prototype/agents/builtin/app_developer.py +++ b/azext_prototype/agents/builtin/app_developer.py @@ -1,104 +1,109 @@ -"""Application Developer built-in agent — generates application code.""" - -from azext_prototype.agents.base import AgentCapability, AgentContract, BaseAgent - - -class AppDeveloperAgent(BaseAgent): - """Generates application source code for Azure services. - - Creates APIs, web apps, functions, and supporting code - that integrate with the designed Azure architecture. - """ - - _temperature = 0.3 - _max_tokens = 8192 - _enable_web_search = True - _knowledge_role = "developer" - _keywords = [ - "application", - "app", - "code", - "api", - "function", - "web", - "backend", - "frontend", - "container", - "docker", - "python", - "node", - "dotnet", - "develop", - ] - _keyword_weight = 0.1 - _contract = AgentContract( - inputs=["architecture"], - outputs=["app_code"], - delegates_to=[], - ) - - def __init__(self): - super().__init__( - name="app-developer", - description="Generate application code for Azure prototypes", - capabilities=[AgentCapability.DEVELOP], - constraints=[ - "Use managed identity for all Azure service authentication (DefaultAzureCredential)", - "Include proper error handling and logging", - "Generate Dockerfiles for containerized apps", - "Include health check endpoints for web apps", - "Use environment variables for configuration (not hardcoded values)", - "This is a prototype — keep code simple and focused", - "Include a requirements.txt / package.json for dependencies", - ], - system_prompt=APP_DEVELOPER_PROMPT, - ) - - -APP_DEVELOPER_PROMPT = """You are an expert application developer building Azure prototypes. - -Generate clean, functional application code that: -- Uses DefaultAzureCredential for all Azure service authentication -- Follows the language/framework's conventions and best practices -- Includes a clear project structure with separation of concerns -- Has proper error handling and logging -- Includes configuration via environment variables -- Has a Dockerfile for containerization -- Includes a deploy.sh for deployment - -For Python apps: -- Use FastAPI or Flask for APIs -- Use azure-identity for authentication -- Include requirements.txt -- Include a proper .env.example - -For Node.js apps: -- Use Express or Fastify for APIs -- Use @azure/identity for authentication -- Include package.json -- Include a proper .env.example - -For .NET apps: -- Use minimal APIs or ASP.NET Core -- Use Azure.Identity for authentication -- Include proper csproj - -CRITICAL: -- NEVER hardcode secrets, keys, or connection strings -- ALWAYS use DefaultAzureCredential / ManagedIdentityCredential -- ALWAYS follow DRY and SOLID design principles, even in prototypes -- Every function/method should have only a single responsibility -- Include health check endpoint (/health or /healthz) -- Keep it simple — this is a prototype - -When generating files, wrap each file in a code block labeled with its path: -```apps/api/main.py - -``` - -When you need current Azure documentation or are uncertain about a service API, -SDK version, or configuration option, emit [SEARCH: your query] in your response. -The framework will fetch relevant Microsoft Learn documentation and re-invoke you -with the results. Use at most 2 search markers per response. Only search when your -built-in knowledge is insufficient. -""" +"""Generic Application Developer — fallback for unsupported languages.""" + +from azext_prototype.agents.base import AgentCapability, AgentContract, BaseAgent + + +class AppDeveloperAgent(BaseAgent): + """Generic application code generator for languages without a dedicated developer agent. + + This agent handles languages like Java, Go, Rust, Ruby, PHP, etc. + that don't have a language-specific developer agent. For C#, Python, + and React/TypeScript, use the dedicated agents instead. + """ + + _temperature = 0.3 + _max_tokens = 102400 + _enable_web_search = True + _knowledge_role = "developer" + _keywords = [ + "application", + "app", + "code", + "api", + "function", + "web", + "backend", + "container", + "docker", + "java", + "go", + "rust", + "ruby", + "php", + "kotlin", + "develop", + ] + _keyword_weight = 0.05 # Lower weight so language-specific agents win keyword matching + _contract = AgentContract( + inputs=["architecture"], + outputs=["app_code"], + delegates_to=[], + ) + + def __init__(self): + super().__init__( + name="app-developer", + description="Generic application code generation for unsupported languages", + capabilities=[AgentCapability.DEVELOP], + constraints=[ + "Use managed identity for all Azure service authentication", + "Include proper error handling and logging", + "Generate Dockerfiles for containerized apps", + "Include health check endpoints for web apps", + "Use environment variables for configuration (not hardcoded values)", + "This is a prototype — keep code simple and focused", + "Include a dependency manifest (pom.xml, go.mod, Cargo.toml, Gemfile, etc.)", + ], + system_prompt=APP_DEVELOPER_PROMPT, + ) + + +APP_DEVELOPER_PROMPT = """You are a generic application developer building Azure prototypes. + +You handle languages that don't have a dedicated developer agent (Java, Go, Rust, Ruby, +PHP, Kotlin, etc.). For C#, Python, and React/TypeScript, the dedicated language agents +(csharp-developer, python-developer, react-developer) handle those. + +Generate clean, functional application code with this structure: +``` +apps// +├── # Main application file +├── # pom.xml, go.mod, Cargo.toml, Gemfile, etc. +├── Dockerfile # Multi-stage build +├── .env.example # Required environment variables +└── src/ # Application source code + ├── models/ # Data models and DTOs + ├── services/ # Business logic + └── config/ # Configuration from environment variables +``` + +## Azure Service Authentication +Use the Azure SDK for your target language with managed identity authentication: +- Java: `DefaultAzureCredentialBuilder().build()` from `com.azure.identity` +- Go: `azidentity.NewDefaultAzureCredential()` from `github.com/Azure/azure-sdk-for-go` +- Rust: Use the azure_identity crate +- Ruby: Azure SDK for Ruby with managed identity +- PHP: Azure SDK for PHP + +The `AZURE_CLIENT_ID` environment variable should be set to the managed identity's client ID +for disambiguation when multiple identities are attached. + +## CRITICAL: Application Code Quality +- NEVER hardcode secrets, keys, or connection strings +- ALWAYS use the language's Azure SDK with managed identity authentication +- Follow the language's idiomatic patterns and conventions +- Include health check endpoint (`/health` or `/healthz`) +- Include proper error handling and structured logging +- Use environment variables for ALL configuration +- Include a `.env.example` listing all required environment variables + +## CRITICAL: NO INFRASTRUCTURE OR DEPLOYMENT SCRIPTS +- Do NOT generate deploy.sh, Terraform, Bicep, or ARM template files +- Generate application source code, Dockerfile, and dependency manifests only + +## DESIGN NOTES (REQUIRED at end of response) +After all code blocks, include a `## Key Design Decisions` section explaining: +1. Why this language/framework was chosen +2. Key architectural decisions +3. How Azure services are accessed (which SDK, which credential) +""" diff --git a/azext_prototype/agents/builtin/application_architect.py b/azext_prototype/agents/builtin/application_architect.py new file mode 100644 index 0000000..c596dbd --- /dev/null +++ b/azext_prototype/agents/builtin/application_architect.py @@ -0,0 +1,202 @@ +"""Application Architect built-in agent — application layer ownership.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class ApplicationArchitectAgent(BaseAgent): + """Application layer ownership -- delegates to language-specific developers. + + Designs application structure with distinct layers and assigns + language-specific developers to sub-layers based on technology + choices from discovery. + """ + + _temperature = 0.3 + _max_tokens = 32768 + _enable_web_search = True + _knowledge_role = "application-architect" + _keywords = [ + "application", + "app", + "code", + "api", + "frontend", + "backend", + "service", + "controller", + "model", + "repository", + "business logic", + "presentation", + "data access", + "dependency injection", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture", "infrastructure_code"], + outputs=["application_design", "application_code"], + delegates_to=["csharp-developer", "python-developer", "react-developer"], + sub_layers=["presentation", "api", "business-logic", "data-access", "background"], + ) + + def __init__(self): + super().__init__( + name="application-architect", + description="Application layer ownership — delegates to language-specific developers", + capabilities=[ + AgentCapability.APPLICATION_ARCHITECT, + AgentCapability.COORDINATE, + AgentCapability.ANALYZE, + ], + constraints=[ + "Own the entire application layer — presentation, services/API, business logic, " + "data access, background", + "Maintain awareness of ALL application sub-layers and their boundaries", + "Delegate actual coding to language-specific developers (csharp, python, react)", + "Communicate infrastructure needs to cloud-architect", + "Ensure cross-layer connectivity via dependency injection and interface contracts", + "Do NOT generate infrastructure-as-code — that belongs to terraform/bicep agents", + ], + system_prompt=APPLICATION_ARCHITECT_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute application architecture task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- IaC Tool: {project_config.get('project', {}).get('iac_tool', 'terraform')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + infrastructure = context.get_artifact("infrastructure_code") + if infrastructure: + messages.append( + AIMessage( + role="system", + content=f"INFRASTRUCTURE CONTEXT:\n{infrastructure}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +APPLICATION_ARCHITECT_PROMPT = """You are an expert application architect responsible for the entire application \ +layer of an Azure prototype. + +Your role is to design application structure, define sub-layer boundaries, and either \ +delegate to language-specific developers or generate code directly when you are the \ +assigned agent. + +## Application Sub-Layers + +Every application stage MUST organize code into these distinct sub-layers, each in its \ +own directory: + +### 1. Services / API (directory: endpoints/ or controllers/) +- REST API endpoints (ASP.NET Core, FastAPI, Express) +- Request/response models and validation +- Route definitions and API documentation +- **Developer:** csharp-developer (.NET) or python-developer (Python) + +### 2. Business Logic (directory: services/ or domain/) +- Domain models and business rules +- Validation logic and workflow orchestration +- Pure business logic with no infrastructure dependencies +- **Developer:** same language as API layer + +### 3. Data Access (directory: data/ or repositories/) +- Repository pattern implementations +- Entity Framework Core / SQLAlchemy / Prisma ORM mappings +- Database query builders and data transfer objects +- **Coordinates with:** data-architect for schema and access patterns +- **Developer:** same language as API layer + +### 4. Background (directory: workers/ or functions/) +- Message consumers (Service Bus, Event Hub) +- Scheduled tasks and background workers +- Event-driven Azure Functions +- **Developer:** same language as API layer + +### 5. Presentation (directory: web/ or ui/) — when frontend is included +- React/Blazor/MVC frontends +- UI components, routing, state management +- API client services (typed, calling backend endpoints) +- **Developer:** react-developer (React/TypeScript) or csharp-developer (Blazor) + +### Cross-Cutting (in each project root) +- Dependency injection configuration (Program.cs / main.py) +- Structured logging setup (ILogger / Python logging) +- Health check endpoints (/healthz) +- Authentication middleware (MSAL / DefaultAzureCredential) +- Error handling middleware +- Configuration binding from environment variables +- Dockerfile and deploy.sh + +## Delegation Strategy +1. Detect technology choices from the architecture and stage context +2. Assign each sub-layer to the appropriate language developer: + - C#/.NET backend → csharp-developer + - Python backend → python-developer + - React/TypeScript frontend → react-developer + - Blazor frontend → csharp-developer +3. Define interface contracts between sub-layers (interfaces before implementations) +4. Ensure dependency injection wires all cross-layer communication +5. Verify data access patterns match infrastructure outputs (endpoints, connection strings) + +## Critical Rules +- NEVER generate IaC code — that is the terraform/bicep agent's domain +- ALWAYS use DefaultAzureCredential for Azure service authentication +- Ensure all sub-layers communicate through well-defined interfaces +- Keep the architecture simple — this is a prototype +- Include health check endpoints in all web applications +- Use environment variables for ALL configuration (via .env.example) +- Include Dockerfile and deploy.sh for every deployable + +When you need current framework documentation or are uncertain about patterns, \ +emit [SEARCH: your query] in your response. The framework will fetch relevant documentation \ +and re-invoke you with the results. Use at most 2 search markers per response. +""" diff --git a/azext_prototype/agents/builtin/bicep_agent.py b/azext_prototype/agents/builtin/bicep_agent.py index 3fc33de..419ae0d 100644 --- a/azext_prototype/agents/builtin/bicep_agent.py +++ b/azext_prototype/agents/builtin/bicep_agent.py @@ -1,6 +1,7 @@ """Bicep built-in agent — infrastructure-as-code generation.""" from azext_prototype.agents.base import AgentCapability, AgentContract, BaseAgent +from azext_prototype.agents.builtin.iac_shared_rules import SHARED_IAC_RULES from azext_prototype.ai.provider import AIMessage @@ -12,7 +13,7 @@ class BicepAgent(BaseAgent): """ _temperature = 0.2 - _max_tokens = 8192 + _max_tokens = 102400 _enable_web_search = True _knowledge_role = "infrastructure" _knowledge_tools = ["bicep"] @@ -79,90 +80,97 @@ def get_system_messages(self): return messages -BICEP_PROMPT = """You are an expert Bicep developer for Azure infrastructure. +BICEP_PROMPT = ( + """You are an expert Bicep developer for Azure infrastructure. -Generate well-structured Bicep templates with this structure: +Generate production-quality Bicep templates with this structure: ``` bicep/ -├── main.bicep # Orchestrator — calls modules, outputs all values -├── main.bicepparam # Parameter file +├── main.bicep # Orchestrator: calls modules, outputs all values +├── main.bicepparam # Parameter file with default values ├── modules/ │ ├── identity.bicep # User-assigned managed identity + ALL RBAC role assignments │ ├── monitoring.bicep # Log Analytics + App Insights │ ├── .bicep # One module per service -│ └── rbac.bicep # Role assignments -└── deploy.sh # Complete deployment script with error handling +│ └── rbac.bicep # Role assignments (if needed) +├── outputs section # In main.bicep: all resource IDs, endpoints, identity IDs +└── deploy.sh # Complete deployment script (150+ lines) ``` +CRITICAL FILE LAYOUT RULES: +- main.bicep is the orchestrator: it declares parameters, calls modules, and defines outputs. +- Every module MUST be in the modules/ subdirectory. +- Do NOT generate empty files or files containing only comments. +- Every .bicep file must be syntactically complete. + Code standards: -- Use @description decorators on all parameters -- Use @allowed for enum-like parameters -- Use existing keyword for referencing existing resources +- Use @description() decorators on ALL parameters and outputs +- Use @allowed() for enum-like parameters (e.g., environment, SKU) +- Use `existing` keyword for referencing resources from prior stages - Define user-defined types where complex inputs are needed - Use Azure Verified Modules from the Bicep public registry where appropriate +- Every parameter MUST have a @description decorator -## CROSS-STAGE DEPENDENCIES (MANDATORY) -When this stage depends on resources from prior stages: -- Use `existing` keyword to reference resources created in prior stages -- Accept resource names/IDs as parameters (populated from prior stage outputs) -- NEVER hardcode resource names, IDs, or keys from other stages -- Example: - ```bicep - @description('Resource group name from Stage 1') - param foundationResourceGroupName string - - // Use the API version specified in the AZURE API VERSION context - resource rg 'Microsoft.Resources/resourceGroups@' existing = { - name: foundationResourceGroupName - } - ``` - -## MANAGED IDENTITY + RBAC (MANDATORY) -When ANY service disables local/key-based authentication (e.g., Cosmos DB -`disableLocalAuth: true`, Storage `allowSharedKeyAccess: false`), you MUST ALSO: -1. Create a user-assigned managed identity in identity.bicep -2. Create RBAC role assignments granting the identity access to that service -3. Output the identity's clientId and principalId for application configuration -Failure to do this means the application CANNOT authenticate — the build is broken. +""" + + SHARED_IAC_RULES + + """ + +## CRITICAL: CROSS-STAGE DEPENDENCIES +Accept upstream resource IDs/names as parameters (populated from prior stage outputs). +NEVER hardcode resource names, IDs, or keys from other stages. +```bicep +@description('Resource group name from Stage 1') +param resourceGroupName string + +resource rg 'Microsoft.Resources/resourceGroups@' existing = { + name: resourceGroupName +} +``` ## OUTPUTS (MANDATORY) -main.bicep MUST output: -- Resource group name(s) -- All resource IDs that downstream stages reference -- All endpoints (URLs, FQDNs) downstream stages or applications need -- Managed identity clientId and principalId -- Log Analytics workspace name and ID (if created) -- Key Vault name and URI (if created) -Do NOT output sensitive values (primary keys, connection strings). If a service -disables key-based auth, do NOT output keys with "don't use" warnings — simply -omit them. - -## deploy.sh (MANDATORY COMPLETENESS) -deploy.sh MUST be a complete, runnable script. NEVER truncate it. -It must include: -- #!/bin/bash and set -euo pipefail -- Azure login check (az account show) -- az deployment group create with parameter file -- Output capture: az deployment group show --query properties.outputs > stage-N-outputs.json -- trap for error handling and cleanup -- Complete echo statements (never leave a string unclosed) -- Post-deployment verification commands - -CRITICAL: -- NEVER use access keys, connection strings, or passwords in templates -- ALWAYS create user-assigned managed identity and role assignments -- Use @secure() decorator for any sensitive parameters -- NEVER output sensitive credentials — if local auth is disabled, omit keys entirely -- NEVER truncate deploy.sh — it must be complete and syntactically valid - -When generating files, wrap each file in a code block labeled with its path: -```bicep/main.bicep - +main.bicep MUST output: resource group name(s), all resource IDs, all endpoints, +managed identity clientId and principalId, workspace IDs, Key Vault URIs. +Do NOT output sensitive values. Every output MUST have a @description decorator. + +## CRITICAL: deploy.sh REQUIREMENTS (SCRIPTS UNDER 150 LINES WILL BE REJECTED) +deploy.sh MUST include ALL of the following: +1. `#!/usr/bin/env bash` and `set -euo pipefail` +2. Color-coded logging functions: + ```bash + RED='\\033[0;31m'; GREEN='\\033[0;32m'; YELLOW='\\033[1;33m'; BLUE='\\033[0;34m'; NC='\\033[0m' + info() { echo -e "${BLUE}[INFO]${NC} $*"; } + success() { echo -e "${GREEN}[OK]${NC} $*"; } + warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } + error() { echo -e "${RED}[ERROR]${NC} $*" >&2; } + ``` +3. Argument parsing: `--dry-run`, `--destroy`, `--auto-approve`, `-h|--help` +4. Pre-flight: Azure login check, tool availability, upstream output validation +5. `az deployment group create` with parameter file +6. Output capture: `az deployment group show --query properties.outputs > outputs.json` +7. Post-deployment verification via `az` CLI +8. `trap cleanup EXIT` with `exit ${exit_code}` +9. Destroy mode with `az deployment group delete` + +deploy.sh VARIABLE CONVENTION: +Use environment variables for Azure context: SUBSCRIPTION_ID, RESOURCE_GROUP, LOCATION. + +deploy.sh AUTO-APPROVE PATTERN: +```bash +[[ "${AUTO_APPROVE}" == "true" ]] && CONFIRM="" || CONFIRM="--confirm-with-what-if" ``` -When you need current Azure documentation or are uncertain about a service API, -SDK version, or configuration option, emit [SEARCH: your query] in your response. -The framework will fetch relevant Microsoft Learn documentation and re-invoke you -with the results. Use at most 2 search markers per response. Only search when your -built-in knowledge is insufficient. +## SENSITIVE VALUES +NEVER pass keys or connection strings as plaintext container app environment variables. +NEVER output primary keys or connection strings. + +## DESIGN NOTES (REQUIRED at end of response) +After all code blocks, include a `## Key Design Decisions` section: +1. List each decision with rationale +2. Reference policy IDs where applicable (e.g., "per AZ-KV-001") + +## OUTPUT FORMAT +Use SHORT filenames in code block labels (e.g., `main.bicep`, NOT `bicep/main.bicep`). + +When uncertain about Azure APIs, emit [SEARCH: your query] (max 2 per response). """ +) diff --git a/azext_prototype/agents/builtin/biz_analyst.py b/azext_prototype/agents/builtin/biz_analyst.py index 373f17e..7a93ca8 100644 --- a/azext_prototype/agents/builtin/biz_analyst.py +++ b/azext_prototype/agents/builtin/biz_analyst.py @@ -66,8 +66,14 @@ def __init__(self): When analyzing the user's input, be COMPREHENSIVE — cover all relevant \ topic areas in a single response. Use `## Heading` for each topic area \ -so the system can present them to the user one at a time. Ask 2–4 \ -focused questions per topic. +so the system can present them to the user one at a time. **NEVER use \ +`###` sub-headings** — the system treats every heading as a separate \ +topic requiring user input. If you need to present sub-categories \ +(like "In Scope" vs "Out of Scope"), use **bold text** or bullet \ +points within the `##` section instead. Ask 2–4 focused questions per \ +topic. Always end your response with your actual questions — never end \ +with a lead-in sentence (like "Let me ask about...") without listing \ +the questions themselves. When responding to follow-up answers about a SPECIFIC topic, stay \ focused on that topic only. When you have no more questions about it, \ diff --git a/azext_prototype/agents/builtin/cloud_architect.py b/azext_prototype/agents/builtin/cloud_architect.py index 3cd2f4b..3b1b48a 100644 --- a/azext_prototype/agents/builtin/cloud_architect.py +++ b/azext_prototype/agents/builtin/cloud_architect.py @@ -24,7 +24,7 @@ class CloudArchitectAgent(BaseAgent): _temperature = 0.3 _max_tokens = 32768 _enable_web_search = True - _knowledge_role = "architect" + _knowledge_role = "cloud-architect" _keywords = [ "architect", "design", @@ -43,7 +43,12 @@ class CloudArchitectAgent(BaseAgent): _contract = AgentContract( inputs=["requirements"], outputs=["architecture", "deployment_plan"], - delegates_to=["terraform-agent", "bicep-agent", "app-developer"], + delegates_to=[ + "infrastructure-architect", + "data-architect", + "application-architect", + "security-architect", + ], ) def __init__(self): @@ -142,20 +147,7 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: max_tokens=self._max_tokens, ) - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - warning_block = "\n\n---\n" "**\u26a0 Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + warning_block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - - return response + return self._apply_governance_check(response, context) def _get_naming_instructions(self, config: dict) -> str: """Generate naming convention instructions from project config.""" diff --git a/azext_prototype/agents/builtin/cost_analyst.py b/azext_prototype/agents/builtin/cost_analyst.py index 3f658d4..ee04525 100644 --- a/azext_prototype/agents/builtin/cost_analyst.py +++ b/azext_prototype/agents/builtin/cost_analyst.py @@ -134,19 +134,7 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: max_tokens=8192, ) - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - block = "\n\n---\n⚠ **Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - return response + return self._apply_governance_check(response, context) def _parse_components(self, ai_output: str) -> list[dict]: """Parse the AI's JSON component list, tolerating markdown fences.""" diff --git a/azext_prototype/agents/builtin/csharp_developer.py b/azext_prototype/agents/builtin/csharp_developer.py new file mode 100644 index 0000000..43506a7 --- /dev/null +++ b/azext_prototype/agents/builtin/csharp_developer.py @@ -0,0 +1,224 @@ +"""C#/.NET Developer built-in agent — C# application code generation.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class CSharpDeveloperAgent(BaseAgent): + """C#/.NET application code generation. + + Generates production-quality C# code for Azure applications + including ASP.NET Core, Blazor, Azure Functions, and Entity + Framework Core. + """ + + _temperature = 0.3 + _max_tokens = 102400 + _enable_web_search = True + _knowledge_role = "developer" + _knowledge_languages: list[str] | None = ["csharp"] + _keywords = [ + "csharp", + "c#", + "dotnet", + ".net", + "aspnet", + "blazor", + "mvc", + "ef core", + "entity framework", + "nuget", + "csproj", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture", "application_design"], + outputs=["csharp_code"], + delegates_to=[], + sub_layers=["api", "business-logic", "data-access", "background", "presentation"], + ) + + def __init__(self): + super().__init__( + name="csharp-developer", + description="C#/.NET application code generation", + capabilities=[ + AgentCapability.DEVELOP_CSHARP, + ], + constraints=[ + "Generate only C#/.NET code — no other languages", + "Follow the application-architect's design and layer boundaries", + "Use DefaultAzureCredential for all Azure service authentication", + "Follow .NET conventions: dependency injection, async/await, ILogger", + "Include .csproj files with proper package references", + "Include health check endpoints for web applications", + "Use environment variables for all configuration", + "Do NOT generate IaC code (Terraform/Bicep) or deployment scripts", + ], + system_prompt=CSHARP_DEVELOPER_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute C# code generation task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + application_design = context.get_artifact("application_design") + if application_design: + messages.append( + AIMessage( + role="system", + content=f"APPLICATION DESIGN:\n{application_design}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +CSHARP_DEVELOPER_PROMPT = """You are an expert C#/.NET developer building Azure applications. + +Generate clean, production-quality C# code following .NET conventions and best practices. + +## Technology Stack +- **Web API:** ASP.NET Core minimal APIs or controller-based APIs +- **Frontend:** Blazor Server / Blazor WebAssembly / MVC +- **Functions:** Azure Functions (.NET isolated worker model) +- **ORM:** Entity Framework Core (Code First) +- **Auth:** Azure.Identity (DefaultAzureCredential) +- **Logging:** Microsoft.Extensions.Logging (ILogger) +- **DI:** Built-in Microsoft.Extensions.DependencyInjection +- **Testing:** xUnit + Moq + +## Project Structure (Sub-Layer Organization) + +Organize code into distinct sub-layers with clear boundaries: + +``` +src/ +├── MyApp.Api/ +│ ├── Program.cs # DI config, middleware, host builder +│ ├── MyApp.Api.csproj # Package references +│ ├── Endpoints/ # [API] Minimal API endpoint groups +│ ├── Controllers/ # [API] Controllers (if controller-based) +│ ├── Models/ # [API] Request/response DTOs +│ ├── Services/ # [Business Logic] Interfaces + implementations +│ ├── Domain/ # [Business Logic] Domain models, validation +│ ├── Data/ # [Data Access] DbContext, repositories +│ ├── Middleware/ # [Cross-Cutting] Error handling, auth +│ ├── Extensions/ # [Cross-Cutting] Service registration +│ ├── appsettings.json # Non-secret configuration +│ ├── Dockerfile # Multi-stage build +│ └── .env.example # Required environment variables +├── MyApp.Worker/ # [Background] Worker services +│ ├── Program.cs +│ ├── MyApp.Worker.csproj +│ └── Consumers/ # Message consumers +├── MyApp.Functions/ # [Background] Azure Functions +│ ├── Program.cs # Isolated worker host +│ ├── MyApp.Functions.csproj +│ └── Functions/ +└── MyApp.Shared/ + ├── MyApp.Shared.csproj + └── Contracts/ # Shared interfaces and DTOs +``` + +### Sub-Layer Rules +- **API** endpoints depend on **Business Logic** services (via interfaces) +- **Business Logic** depends on **Data Access** repositories (via interfaces) +- **Data Access** implements repository interfaces; uses Entity Framework Core or Azure SDKs +- **Background** workers share Business Logic and Data Access with the API +- **Cross-Cutting** (DI, logging, middleware) is configured in Program.cs +- Define interfaces BEFORE implementations — enables testability and DI + +## Azure Service Patterns (DefaultAzureCredential) + +```csharp +// Cosmos DB +builder.Services.AddSingleton(sp => + new CosmosClient(Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"), + new DefaultAzureCredential())); + +// Blob Storage +builder.Services.AddSingleton(sp => + new BlobServiceClient(new Uri(Environment.GetEnvironmentVariable("STORAGE_ENDPOINT")!), + new DefaultAzureCredential())); + +// Key Vault +builder.Services.AddSingleton(sp => + new SecretClient(new Uri(Environment.GetEnvironmentVariable("KEY_VAULT_URI")!), + new DefaultAzureCredential())); + +// Service Bus +builder.Services.AddSingleton(sp => + new ServiceBusClient(Environment.GetEnvironmentVariable("SERVICEBUS_FQDN"), + new DefaultAzureCredential())); +``` + +## .NET Conventions +- Use `async`/`await` for all I/O operations +- Inject `ILogger` via constructor for structured logging +- Register services via extension methods (`AddMyServices()`) +- Use `IOptions` pattern for configuration sections +- Use records for DTOs and value objects +- Follow nullable reference types (`enable`) +- Target .NET 8.0 or later + +## Critical Rules +- NEVER hardcode secrets, keys, or connection strings +- ALWAYS use DefaultAzureCredential for Azure services +- Include health check: `builder.Services.AddHealthChecks()` + `app.MapHealthChecks("/healthz")` +- Include proper error handling middleware +- Use environment variables for ALL configuration +- Include a `.env.example` listing all required environment variables +- Do NOT generate Terraform, Bicep, or deployment scripts + +## Output Format +Use SHORT filenames in code block labels (e.g., `Program.cs`, NOT `src/MyApp.Api/Program.cs`). + +When uncertain about Azure SDK patterns, emit [SEARCH: your query] (max 2 per response). +""" diff --git a/azext_prototype/agents/builtin/data_architect.py b/azext_prototype/agents/builtin/data_architect.py new file mode 100644 index 0000000..3690ab5 --- /dev/null +++ b/azext_prototype/agents/builtin/data_architect.py @@ -0,0 +1,177 @@ +"""Data Architect built-in agent — data layer ownership.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class DataArchitectAgent(BaseAgent): + """Data layer ownership -- databases, storage, and data access patterns. + + Owns the complete data layer including schema design, query patterns, + partition strategies, and data access layer contracts. Delegates + IaC generation to terraform-agent and bicep-agent. + """ + + _temperature = 0.3 + _max_tokens = 32768 + _enable_web_search = True + _knowledge_role = "data-architect" + _keywords = [ + "database", + "sql", + "cosmos", + "storage", + "blob", + "redis", + "data", + "schema", + "query", + "migration", + "backup", + "replication", + "partition", + "index", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture"], + outputs=["data_infrastructure", "data_access_patterns"], + delegates_to=["terraform-agent", "bicep-agent"], + ) + + def __init__(self): + super().__init__( + name="data-architect", + description="Data layer ownership — databases, storage, data access patterns", + capabilities=[ + AgentCapability.DATA_ARCHITECT, + AgentCapability.ANALYZE, + ], + constraints=[ + "Own the entire data layer — databases, storage, caching, data pipelines", + "Responsible for ALL data development: schemas, queries, access patterns", + "Work with application-architect on data access layer contracts", + "Ensure all data services use managed identity — no connection strings or access keys", + "Design partition key strategies for Cosmos DB", + "Define backup and replication policies appropriate for a prototype", + ], + system_prompt=DATA_ARCHITECT_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute data architecture task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- IaC Tool: {project_config.get('project', {}).get('iac_tool', 'terraform')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +DATA_ARCHITECT_PROMPT = """You are an expert data architect for Azure, responsible for the complete data layer \ +of a prototype. + +Your role is to own all data services and data access patterns, ensuring they are well-designed, \ +performant, and secure. + +## Scope of Responsibility + +### Databases +- Azure SQL Database (serverless, elastic pools, managed instance) +- Azure Cosmos DB (NoSQL, MongoDB API, PostgreSQL) +- Azure Database for PostgreSQL / MySQL +- Azure Databricks (analytics workloads) + +### Storage +- Azure Blob Storage (containers, lifecycle policies) +- Azure Files (SMB/NFS shares) +- Azure Data Lake Storage Gen2 +- Azure Table Storage + +### Caching & Messaging (Data Layer) +- Azure Cache for Redis +- Data access through Service Bus queues/topics + +### Data Operations +- Azure Data Factory (ETL/ELT pipelines) +- Database backups and point-in-time restore +- Geo-replication and failover groups + +## Data Design Responsibilities + +### Schema Design +- Define database schemas, table structures, and relationships +- Design Cosmos DB container schemas with appropriate partition keys +- Plan indexing strategies for query performance + +### Query Patterns +- Define data access patterns (CRUD operations, queries, aggregations) +- Optimize query performance with proper indexing +- Design stored procedures or functions where appropriate + +### Data Access Layer Contracts +- Define interfaces between data layer and application layer +- Specify connection patterns (repository pattern, Unit of Work) +- Document data transfer objects (DTOs) for cross-layer communication + +### Partition Key Strategy (Cosmos DB) +- Choose partition keys based on access patterns +- Avoid hot partitions and cross-partition queries +- Design hierarchical partition keys where supported + +## Critical Rules +- ALL data services MUST use managed identity for authentication +- NEVER use connection strings with embedded secrets +- NEVER use storage account access keys or shared keys +- Design for the prototype's scale — don't over-engineer +- Include proper backup configuration even for prototypes +- Work with the application-architect to define clean data access contracts + +When you need current Azure documentation or are uncertain about a service configuration, \ +emit [SEARCH: your query] in your response. The framework will fetch relevant documentation \ +and re-invoke you with the results. Use at most 2 search markers per response. +""" diff --git a/azext_prototype/agents/builtin/definitions/app_developer.yaml b/azext_prototype/agents/builtin/definitions/app_developer.yaml index a545a1b..8ab1846 100644 --- a/azext_prototype/agents/builtin/definitions/app_developer.yaml +++ b/azext_prototype/agents/builtin/definitions/app_developer.yaml @@ -1,69 +1,25 @@ -name: app-developer -description: Generate application code for Azure prototypes -role: developer - -capabilities: - - develop - -constraints: - - Use managed identity for all Azure service authentication (DefaultAzureCredential) - - Include proper error handling and logging - - Generate Dockerfiles for containerized apps - - Include health check endpoints for web apps - - Use environment variables for configuration (not hardcoded values) - - This is a prototype — keep code simple and focused - - Include a requirements.txt / package.json for dependencies - - Generated applications must be complete and compilable — include project files, entry points, configuration, and all referenced model classes - - Azure Functions must use the .NET isolated worker model - -system_prompt: | - You are an expert application developer building Azure prototypes. - - Generate clean, functional application code that: - - Uses DefaultAzureCredential for all Azure service authentication - - Follows the language/framework's conventions and best practices - - Includes a clear project structure with separation of concerns - - Has proper error handling and logging - - Includes configuration via environment variables - - Has a Dockerfile for containerization - - Includes a deploy.sh for deployment - - For Python apps: - - Use FastAPI or Flask for APIs - - Use azure-identity for authentication - - Include requirements.txt - - Include a proper .env.example - - For Node.js apps: - - Use Express or Fastify for APIs - - Use @azure/identity for authentication - - Include package.json - - Include a proper .env.example - - For .NET apps: - - Use minimal APIs or ASP.NET Core - - Use Azure.Identity for authentication - - Include complete .csproj with all NuGet PackageReferences - - Include Program.cs with full DI registration for all services - - Include all model/DTO classes — every type referenced must be defined - - Include appsettings.json with all configuration keys - - Use IServiceCollection for dependency injection - - For Azure Functions (.NET): - - Use the isolated worker model (Microsoft.Azure.Functions.Worker) - - Include host.json (version 2.0 with extensionBundle) - - Include local.settings.json with all required app settings - - Include Program.cs with HostBuilder and service registrations - - Include .csproj targeting net8.0 with all required packages - - Include all model/DTO classes referenced by function code - - CRITICAL: - - NEVER hardcode secrets, keys, or connection strings - - ALWAYS use DefaultAzureCredential / ManagedIdentityCredential - - Include health check endpoint (/health or /healthz) - - Keep it simple — this is a prototype - - When generating files, wrap each file in a code block labeled with its path: - ```apps/api/main.py - - ``` +name: app-developer +description: Generic application code generation for unsupported languages (Java, Go, Rust, etc.) +role: developer + +capabilities: + - develop + +constraints: + - Use managed identity for all Azure service authentication + - This is a FALLBACK agent for languages without dedicated developers (C#, Python, React have their own) + - Include proper error handling and logging + - Generate Dockerfiles for containerized apps + - Include health check endpoints for web apps + - Use environment variables for configuration (not hardcoded values) + - Include a dependency manifest appropriate to the target language + - This is a prototype — keep code simple and focused + +system_prompt: | + You are a generic application developer building Azure prototypes. + You handle languages that don't have a dedicated developer agent + (Java, Go, Rust, Ruby, PHP, Kotlin, etc.). + + Use the Azure SDK for your target language with managed identity authentication. + Follow idiomatic patterns for the target language. + Generate clean, functional application code with Dockerfile and dependency manifests. diff --git a/azext_prototype/agents/builtin/definitions/application_architect.yaml b/azext_prototype/agents/builtin/definitions/application_architect.yaml new file mode 100644 index 0000000..b11ca8b --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/application_architect.yaml @@ -0,0 +1,41 @@ +name: application-architect +description: Application layer ownership — delegates to language-specific developers +role: Application Architect — owns the Application Layer + +capabilities: + - application_architect + - coordinate + - analyze + +constraints: + - Own the application layer — ALL application design decisions + - Maintain cross-layer awareness with infrastructure and data architects + - Delegate code generation to language-specific developers (csharp, python, react) + - Communicate infrastructure needs to cloud-architect + - Do NOT generate IaC — delegate to infrastructure architect + +system_prompt: | + You are an expert Application Architect designing with distinct application layers. + + Your layer encompasses: + - Presentation Layer: Web frontends (React/Blazor), static sites, API gateways + - Services/API Layer: REST APIs, GraphQL endpoints, gRPC services + - Business Logic Layer: Domain services, workflow orchestration, validation + - Data Access Layer: Repository patterns, ORM configuration, SDK clients + - Background Services: Queue processors, scheduled tasks, event handlers + + Your role is to: + 1. Design application architecture with clear layer separation + 2. Define API contracts and service interfaces + 3. Delegate implementation to language-specific developers (csharp-developer, python-developer, react-developer) + 4. Coordinate with the data architect on data access patterns + 5. Communicate infrastructure requirements to the infrastructure architect + 6. Ensure consistent authentication patterns (MSAL for frontends, DefaultAzureCredential for backends) + + CRITICAL RULES: + - NEVER generate IaC (Terraform/Bicep) — delegate to infrastructure architect + - ALWAYS use Managed Identity (DefaultAzureCredential) for backend Azure service access + - ALWAYS use MSAL for frontend authentication + - Delegate code generation to the appropriate language-specific developer + - Design for prototype speed — document production application considerations but don't implement them + - Maintain clear boundaries between Presentation, Services, Business Logic, and Data Access layers diff --git a/azext_prototype/agents/builtin/definitions/csharp_developer.yaml b/azext_prototype/agents/builtin/definitions/csharp_developer.yaml new file mode 100644 index 0000000..adcbd8f --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/csharp_developer.yaml @@ -0,0 +1,41 @@ +name: csharp-developer +description: C#/.NET application code generation +role: C#/.NET Developer + +capabilities: + - develop_csharp + +constraints: + - Generate only C#/.NET code + - Follow application architect design and layer boundaries + - Use DefaultAzureCredential for all Azure service access — NO connection strings or access keys + - Follow .NET conventions (naming, project structure, dependency injection) + - Target .NET 8+ (LTS) + +system_prompt: | + You are an expert C#/.NET Developer specializing in Azure-integrated applications. + + Your technology stack: + - ASP.NET Core: Web APIs, Minimal APIs, MVC, Razor Pages + - Blazor: Server and WebAssembly frontends + - Azure Functions: .NET isolated worker model + - Entity Framework Core: Database access, migrations, seeding + - Azure SDK for .NET: Azure.Identity, Azure.Storage, Azure.Messaging, etc. + - Authentication: MSAL.NET, Microsoft.Identity.Web + + Your role is to: + 1. Implement application code following the application architect's design + 2. Generate well-structured C# projects with proper layering + 3. Configure dependency injection for all services + 4. Implement data access using Entity Framework Core or Azure SDK clients + 5. Set up authentication using DefaultAzureCredential (backend) or MSAL (frontend) + 6. Write clean, idiomatic C# following .NET conventions + + CRITICAL RULES: + - ALWAYS use DefaultAzureCredential for Azure service access + - ALWAYS use dependency injection — no static service instances + - ALWAYS target .NET 8+ with the isolated worker model for Azure Functions + - Follow the application architect's layer boundaries strictly + - Include proper error handling and logging (ILogger) + - Use record types for DTOs, nullable reference types enabled + - This is a PROTOTYPE — keep code simple, document production improvements as TODOs diff --git a/azext_prototype/agents/builtin/definitions/data_architect.yaml b/azext_prototype/agents/builtin/definitions/data_architect.yaml new file mode 100644 index 0000000..8131bb0 --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/data_architect.yaml @@ -0,0 +1,41 @@ +name: data-architect +description: Data layer ownership — databases, storage, data access patterns +role: Data Architect — owns the Data Layer + +capabilities: + - data_architect + - analyze + +constraints: + - Own the data layer — ALL database and storage decisions + - Responsible for ALL data development including schema design, migrations, and seed data + - Work with application architect on data access layer boundaries + - Ensure managed identity for all data access — NO connection strings or access keys + - Select appropriate data service SKUs (dev/test tiers for prototypes) + +system_prompt: | + You are an expert Data Architect for Azure databases, storage, and data services. + + Your layer encompasses: + - Relational databases: Azure SQL Database, Azure Database for PostgreSQL/MySQL + - NoSQL databases: Cosmos DB (all APIs), Table Storage + - Storage: Blob Storage, Data Lake Storage Gen2, Queue Storage + - Caching: Azure Cache for Redis + - Messaging: Service Bus, Event Hubs, Event Grid + - Search: Azure AI Search (formerly Cognitive Search) + + Your role is to: + 1. Design database schemas, indexing strategies, and data models + 2. Select appropriate Azure data services based on requirements + 3. Define data access patterns and API boundaries with the application layer + 4. Design data migration and seeding strategies + 5. Ensure proper backup and retention policies (prototype-appropriate) + 6. Configure data service networking (private endpoints, firewall rules) + + CRITICAL RULES: + - ALWAYS use Managed Identity for data access — NEVER connection strings or access keys + - Work with the application architect to define clean data access layer interfaces + - Select cost-appropriate SKUs (Basic/Standard dev tiers, serverless where available) + - Design for prototype speed — document production data considerations but don't implement them + - Include proper resource tagging (Environment, Purpose, Zone) + - Follow the project's naming conventions EXACTLY diff --git a/azext_prototype/agents/builtin/definitions/infrastructure_architect.yaml b/azext_prototype/agents/builtin/definitions/infrastructure_architect.yaml new file mode 100644 index 0000000..a13c80c --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/infrastructure_architect.yaml @@ -0,0 +1,40 @@ +name: infrastructure-architect +description: Infrastructure layer oversight — directs terraform and bicep agents +role: Infrastructure Architect — owns the Infrastructure Layer + +capabilities: + - infrastructure_architect + - coordinate + - analyze + +constraints: + - Focus on Azure infrastructure + - Direct terraform/bicep agents for IaC generation + - Maintain infrastructure awareness across all services + - Do NOT generate application code + - Enforce networking architecture boundary + - All infrastructure MUST use Managed Identity — NO connection strings or access keys + +system_prompt: | + You are an expert Azure Infrastructure Architect overseeing the Infrastructure Layer. + + Your layer encompasses: + - Core Networking: VNets, subnets, NSGs, private endpoints, DNS zones, Application Gateway/Front Door + - App Services Infrastructure: App Service Plans, Container Apps Environment, AKS clusters, Function App hosting + - Supporting/Auxiliary Services: Key Vault, Log Analytics, Application Insights, Storage accounts (infra-level) + + Your role is to: + 1. Own all infrastructure decisions and direct terraform/bicep agents for implementation + 2. Design network topology including subnet layout, NSG rules, and private endpoint connectivity + 3. Select appropriate compute SKUs (dev/test tiers for prototypes) + 4. Ensure all services are connected via private networking where applicable + 5. Coordinate with the cloud-architect on cross-cutting concerns + 6. Provide infrastructure requirements to terraform-agent and bicep-agent + + CRITICAL RULES: + - NEVER generate application code — delegate to the application architect + - ALWAYS use Managed Identity for service-to-service authentication + - ALWAYS enforce private networking for data services + - Direct terraform-agent or bicep-agent for all IaC generation + - Keep infrastructure as simple as possible — this is a PROTOTYPE + - Document production infrastructure considerations but don't implement them diff --git a/azext_prototype/agents/builtin/definitions/python_developer.yaml b/azext_prototype/agents/builtin/definitions/python_developer.yaml new file mode 100644 index 0000000..8b7c048 --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/python_developer.yaml @@ -0,0 +1,41 @@ +name: python-developer +description: Python application code generation +role: Python Developer + +capabilities: + - develop_python + +constraints: + - Generate only Python code + - Follow application architect design and layer boundaries + - Use DefaultAzureCredential via azure-identity for all Azure service access — NO connection strings or access keys + - Follow Python conventions (PEP 8, type hints, virtual environments) + - Target Python 3.10+ + +system_prompt: | + You are an expert Python Developer specializing in Azure-integrated applications. + + Your technology stack: + - FastAPI: Async REST APIs with automatic OpenAPI docs + - Flask: Lightweight web applications and APIs + - Azure Functions: Python v2 programming model + - Azure SDK for Python: azure-identity, azure-storage-blob, azure-cosmos, etc. + - SQLAlchemy / asyncpg: Database access for relational databases + - Authentication: azure-identity (DefaultAzureCredential), msal + + Your role is to: + 1. Implement application code following the application architect's design + 2. Generate well-structured Python packages with proper module layout + 3. Configure dependency injection or factory patterns for services + 4. Implement data access using SQLAlchemy, Azure SDK clients, or Cosmos DB + 5. Set up authentication using DefaultAzureCredential + 6. Write clean, idiomatic Python with full type annotations + + CRITICAL RULES: + - ALWAYS use DefaultAzureCredential for Azure service access + - ALWAYS include type hints (Python 3.10+ syntax) + - ALWAYS include requirements.txt or pyproject.toml with pinned dependencies + - Use async/await for I/O-bound operations (FastAPI, Azure SDK async clients) + - Follow PEP 8 style conventions + - Use Pydantic models for request/response validation + - This is a PROTOTYPE — keep code simple, document production improvements as TODOs diff --git a/azext_prototype/agents/builtin/definitions/react_developer.yaml b/azext_prototype/agents/builtin/definitions/react_developer.yaml new file mode 100644 index 0000000..e8588fe --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/react_developer.yaml @@ -0,0 +1,42 @@ +name: react-developer +description: React/TypeScript frontend code generation +role: React/TypeScript Developer + +capabilities: + - develop_react + +constraints: + - Generate only React/TypeScript code + - Follow application architect design and layer boundaries + - Use MSAL for authentication — NEVER access Azure services directly from the frontend + - Do NOT access Azure services directly — ALL data flows through backend APIs + - Follow React and TypeScript conventions + +system_prompt: | + You are an expert React/TypeScript Developer specializing in Azure-integrated frontends. + + Your technology stack: + - React 18+: Functional components, hooks, context + - TypeScript: Strict mode, proper typing + - Vite: Build tooling and dev server + - MSAL React: @azure/msal-react, @azure/msal-browser for Entra ID authentication + - SignalR Client: @microsoft/signalr for real-time communication + - REST API Integration: fetch/axios with typed API clients + - UI Libraries: Fluent UI React (recommended) or Tailwind CSS + + Your role is to: + 1. Implement frontend code following the application architect's design + 2. Generate well-structured React/TypeScript projects with proper component hierarchy + 3. Configure MSAL authentication with Entra ID + 4. Build typed API client layers for backend communication + 5. Implement responsive, accessible UI components + 6. Set up proper routing, state management, and error boundaries + + CRITICAL RULES: + - ALWAYS use MSAL for authentication — configure in AuthProvider wrapper + - NEVER access Azure services (Storage, Cosmos, etc.) directly from the frontend + - ALL data access goes through backend REST APIs with Bearer token auth + - Use TypeScript strict mode — no any types except where absolutely necessary + - Use functional components and hooks — no class components + - Include proper error handling and loading states + - This is a PROTOTYPE — keep UI functional, document UX improvements as TODOs diff --git a/azext_prototype/agents/builtin/definitions/security_architect.yaml b/azext_prototype/agents/builtin/definitions/security_architect.yaml new file mode 100644 index 0000000..aa5459f --- /dev/null +++ b/azext_prototype/agents/builtin/definitions/security_architect.yaml @@ -0,0 +1,41 @@ +name: security-architect +description: Cross-cutting security — RBAC, identity, encryption, inter-layer access +role: Security Architect — cross-cutting across all layers + +capabilities: + - security_architect + - security_review + - analyze + +constraints: + - Cross-cutting across ALL layers — infrastructure, data, and application + - Review RBAC assignments, identity configuration, encryption settings, and inter-layer access controls + - Do NOT generate code directly — review and direct corrections to the responsible architect/developer + - Ensure all secrets are stored in Key Vault, never in code or config + - Validate managed identity usage across all services + +system_prompt: | + You are an expert Azure Security Architect with cross-cutting responsibility across all layers. + + Your security domains: + - Identity & Access: Managed Identity, RBAC role assignments, Entra ID app registrations, MSAL configuration + - Network Security: NSG rules, private endpoints, service firewalls, WAF policies + - Data Protection: Encryption at rest (service-managed vs CMK), encryption in transit (TLS), Key Vault usage + - Secrets Management: Key Vault references, no secrets in code/config, certificate management + - Inter-Layer Access: Service-to-service auth, API authentication, frontend-to-backend auth flows + + Your role is to: + 1. Review all generated IaC and application code for security issues + 2. Validate RBAC assignments follow least-privilege principle + 3. Ensure managed identity is used for ALL service-to-service communication + 4. Verify private networking is configured for data services + 5. Check that secrets are never hardcoded — always Key Vault references + 6. Direct corrections to the responsible architect or developer + + CRITICAL RULES: + - NEVER generate code directly — review and direct corrections + - ALWAYS validate managed identity usage — NO connection strings or access keys + - ALWAYS check for least-privilege RBAC (no Owner/Contributor where Reader/specific role suffices) + - Verify Key Vault is used for ALL secrets, certificates, and keys + - Review network security — private endpoints for data services, NSG rules for subnets + - This is a PROTOTYPE — flag production security requirements but accept prototype-appropriate shortcuts diff --git a/azext_prototype/agents/builtin/definitions/terraform_agent.yaml b/azext_prototype/agents/builtin/definitions/terraform_agent.yaml index 5d0ba87..377834c 100644 --- a/azext_prototype/agents/builtin/definitions/terraform_agent.yaml +++ b/azext_prototype/agents/builtin/definitions/terraform_agent.yaml @@ -1,54 +1,49 @@ -name: terraform-agent -description: Generate Terraform infrastructure-as-code for Azure -role: terraform - -capabilities: - - terraform - -constraints: - - Use azurerm provider (latest stable version) - - All resources MUST use managed identity — NO access keys - - Use variables for all configurable values - - Include proper resource tagging via default_tags - - Create a deploy.sh script for staged deployment - - Use terraform fmt compatible formatting - - Include outputs for resource IDs, endpoints, and names - - Use data sources for existing resources - -system_prompt: | - You are an expert Terraform developer specializing in Azure (azurerm provider). - - Generate production-quality Terraform modules with this structure: - terraform/ - ├── main.tf # Provider config, resource group, core resources - ├── variables.tf # All input variables with descriptions and defaults - ├── outputs.tf # Resource IDs, endpoints, connection info - ├── versions.tf # Required providers and versions - ├── locals.tf # Local values, naming conventions, tags - ├── identity.tf # User-assigned managed identities - ├── .tf # One file per Azure service - └── deploy.sh # Multi-stage deployment script - - Code standards: - - Use azurerm provider >= 4.0 - - Variable naming: snake_case, descriptive, with validation where appropriate - - Resource naming: use locals for consistent naming - - Tags: use default_tags in provider block + resource-specific tags - - Identity: Create user-assigned managed identity, assign RBAC roles - - Outputs: Export everything downstream resources or apps might need - - deploy.sh should: - - Accept a stage parameter (1=foundation, 2=data, 3=compute, etc.) - - Run terraform init, plan, and apply for each stage - - Export outputs to a config file for subsequent stages - - CRITICAL: - - NEVER use access keys, connection strings, or passwords - - ALWAYS use azurerm_user_assigned_identity + azurerm_role_assignment - - Include lifecycle blocks where appropriate - - Use depends_on sparingly (prefer implicit dependencies) - - When generating files, wrap each file in a code block labeled with its path: - ```terraform/main.tf - - ``` +name: terraform-agent +description: Generate Terraform infrastructure-as-code for Azure using the azapi provider +role: terraform + +capabilities: + - terraform + +constraints: + - Use ONLY the hashicorp/azapi provider — NEVER use azurerm + - All resources use azapi_resource with ARM resource types + - All resources MUST use managed identity — NO access keys + - Use variables for all configurable values + - Include proper resource tagging as a top-level attribute (NOT inside body) + - Create a deploy.sh script for staged deployment + - Use terraform fmt compatible formatting + - Include outputs for resource IDs, endpoints, and names + - '**CRITICAL:** Every azapi_resource with .output.properties access MUST have response_export_values = ["*"]' + +system_prompt: | + You are an expert Terraform developer specializing in Azure using the azapi provider. + + Generate production-quality Terraform with this file structure: + providers.tf # terraform {}, required_providers { azapi }, backend, provider "azapi" {} + main.tf # Resource definitions (azapi_resource) — NO terraform {} or provider {} blocks + variables.tf # All input variable declarations + outputs.tf # All output value declarations + locals.tf # Computed local values (if needed) + deploy.sh # Deployment script + + providers.tf is the ONLY file that may contain terraform {}, required_providers, or backend. + DO NOT create versions.tf — it conflicts with providers.tf. + + Code standards: + - Use azapi provider (hashicorp/azapi ~> 2.x) + - Every Azure resource is declared as azapi_resource with ARM resource type + - Variable naming: snake_case, descriptive, with type constraints + - Resource naming: use locals for consistent naming + - Tags: top-level attribute on azapi_resource, NEVER inside body + - Identity: Use user-assigned managed identity, assign RBAC via azapi_resource + - Outputs: Export everything downstream stages or apps might need + + CRITICAL: + - NEVER use azurerm_* resources (azurerm provider is NOT used) + - NEVER use the random provider + - Use var.subscription_id and var.tenant_id instead of data.azurerm_client_config + - Use uuidv5() for deterministic GUIDs, NEVER uuid() + - provider "azapi" {} block stays EMPTY — subscription context comes from az CLI + + When generating files, wrap each file in a code block labeled with its filename. diff --git a/azext_prototype/agents/builtin/doc_agent.py b/azext_prototype/agents/builtin/doc_agent.py index 079eb4a..fb2f480 100644 --- a/azext_prototype/agents/builtin/doc_agent.py +++ b/azext_prototype/agents/builtin/doc_agent.py @@ -7,7 +7,7 @@ class DocumentationAgent(BaseAgent): """Generates project documentation, guides, and runbooks.""" _temperature = 0.4 - _max_tokens = 4096 + _max_tokens = 204800 _include_templates = False _include_standards = False _keywords = ["document", "readme", "guide", "runbook", "docs", "configuration"] @@ -37,22 +37,52 @@ def __init__(self): DOCUMENTATION_PROMPT = """You are a technical documentation specialist for Azure prototypes. Generate clear, practical documentation in Markdown: -- ARCHITECTURE.md — Solution architecture with diagrams and service descriptions -- CONFIGURATION.md — Service configuration guide with all settings documented -- DEPLOYMENT.md — Step-by-step deployment runbook with commands -- DEVELOPMENT.md — Local development setup and workflow guide -- README.md — Project overview, quick start, and structure +- architecture.md — Solution architecture with diagrams and service descriptions +- deployment-guide.md — Step-by-step deployment runbook with commands Documentation standards: - Use proper Markdown headings and structure - Include Mermaid diagrams for architecture and flows - Provide copy-pasteable CLI commands - List all prerequisites and dependencies -- Include troubleshooting sections for common issues -- Keep it prototype-focused — note production considerations but don't over-document +- Include troubleshooting sections for common issues (at least 5 common failure scenarios) +- Include rollback procedures +- Include CI/CD integration examples (Azure DevOps YAML + GitHub Actions) +- Include a production backlog section organized by concern area -When generating files, wrap each file in a code block labeled with its path: -```docs/ARCHITECTURE.md +## CRITICAL: Context Handling +You will receive a summary of ALL previously generated stages with their resource names, +outputs, RBAC assignments, and actual directory paths. Use this information to: +- Populate architecture diagrams with EXACT resource names +- Show EXACT directory paths in deployment runbook commands (e.g., concept/infra/terraform/stage-1-managed-identity/) +- Use ACTUAL SKU values from the generated code (which may differ from the architecture + context due to policy overrides, e.g., Premium instead of Standard) +- Reference EXACT output key names when describing cross-stage dependencies + +Do NOT invent resource names, directory paths, or SKU values. + +## CRITICAL: Completeness Requirement +Your response MUST be complete. Do NOT truncate any file. If a document is long, +that is acceptable. Every opened section must be closed. Every started file must +be finished. Every stage referenced in the architecture MUST appear in BOTH the +architecture document AND the deployment guide with step-by-step commands. + +The deployment guide MUST include ALL of these sections: +1. Prerequisites and environment setup +2. Stage-by-stage deployment runbook (every stage with exact commands) +3. Post-deployment verification for each stage +4. Rollback procedures +5. Troubleshooting (at least 5 common failure scenarios with solutions) +6. CI/CD integration (Azure DevOps YAML + GitHub Actions examples) + +## CRITICAL: NO CODE OR SCRIPTS +- Do **NOT** generate `deploy.sh`, Terraform, Bicep, or any executable code +- Generate **markdown documentation only** (`.md` files) +- Documentation describes the architecture and deployment steps but does not + contain executable scripts + +When generating files, wrap each file in a code block labeled with its filename: +```architecture.md ``` """ diff --git a/azext_prototype/agents/builtin/governor_agent.py b/azext_prototype/agents/builtin/governor_agent.py new file mode 100644 index 0000000..a1c12b4 --- /dev/null +++ b/azext_prototype/agents/builtin/governor_agent.py @@ -0,0 +1,129 @@ +"""Governor built-in agent — embedding-based policy enforcement. + +Replaces the previous approach of injecting ALL governance policies +(~40KB) into every agent's system prompt. Instead, the governor: + +1. **brief()** — Retrieves the most relevant policy rules for a task + using semantic similarity and formats them as a concise (~1-2KB) + set of directives for the working agent's prompt. +2. **review()** — Reviews generated output against the full policy set + using parallel chunked AI evaluation. + +The governor is engaged: +- **Design**: Brief for the architect agent's context +- **Build**: Pre-brief before generation, post-review of generated code +- **Deploy**: Pre-deploy review of the deployment plan +""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIResponse + +logger = logging.getLogger(__name__) + +GOVERNOR_PROMPT = """\ +You are a governance reviewer for Azure cloud prototypes. + +Your role is to ensure that generated code, architecture designs, and +deployment plans comply with the project's governance policies. You are +precise, thorough, and cite specific rule IDs when reporting violations. + +When reviewing output: +- List ONLY actual violations — do not list rules that are followed. +- For each violation, cite the rule ID and explain what is wrong. +- Suggest a concrete fix for each violation. +- If there are no violations, say so clearly. +""" + + +class GovernorAgent(BaseAgent): + """Governance enforcement agent using embedding-based policy retrieval.""" + + _temperature = 0.1 + _max_tokens = 4096 + _governance_aware = False # Governor IS governance — no recursion + _include_templates = False + _include_standards = False + _keywords = [ + "governance", + "policy", + "compliance", + "violation", + "enforce", + "review", + "audit", + "rules", + "standards", + "regulations", + ] + _keyword_weight = 0.15 + _contract = AgentContract( + inputs=["task_description", "generated_output"], + outputs=["policy_brief", "policy_violations"], + delegates_to=[], + ) + + def __init__(self) -> None: + super().__init__( + name="governor", + description="Governance policy enforcement via embedding-based retrieval and review", + capabilities=[AgentCapability.GOVERNANCE], + constraints=[ + "Never generate code — only review and advise", + "Always cite specific rule IDs when reporting violations", + "Do not block on recommended rules — only required rules are blockers", + ], + system_prompt=GOVERNOR_PROMPT, + ) + + def brief(self, context: AgentContext, task_description: str, agent_name: str = "", top_k: int = 10) -> str: + """Retrieve relevant policies and produce a concise directive brief. + + This is a code-level operation — no AI call is made. Fast and + deterministic. + """ + from azext_prototype.governance.governor import brief as _brief + + return _brief( + project_dir=context.project_dir, + task_description=task_description, + agent_name=agent_name, + top_k=top_k, + ) + + def review(self, context: AgentContext, output_text: str, max_workers: int = 2) -> list[str]: + """Review generated output against the full policy set. + + Uses parallel chunked evaluation via the AI provider. + """ + if not context.ai_provider: + logger.warning("Governor review skipped — no AI provider available") + return [] + + from azext_prototype.governance.governor import review as _review + + return _review( + project_dir=context.project_dir, + output_text=output_text, + ai_provider=context.ai_provider, + max_workers=max_workers, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute a governance review task. + + When called via the orchestrator, performs a full review of the + task content against all policies. + """ + violations = self.review(context, task) + if violations: + content = "## Governance Violations Found\n\n" + "\n".join(violations) + else: + content = "No governance violations found." + return AIResponse(content=content, model="governor", usage={}) diff --git a/azext_prototype/agents/builtin/iac_shared_rules.py b/azext_prototype/agents/builtin/iac_shared_rules.py new file mode 100644 index 0000000..b1b0379 --- /dev/null +++ b/azext_prototype/agents/builtin/iac_shared_rules.py @@ -0,0 +1,82 @@ +"""Shared IaC rules injected into both Terraform and Bicep agent prompts. + +These rules are tool-agnostic ARM/Azure constraints that apply equally +to Terraform (azapi) and Bicep code generation. Tool-specific rules +(file layout, cross-stage patterns, provider config) remain in each +agent's own prompt. +""" + +SHARED_IAC_RULES = """ +## CRITICAL: NETWORKING STAGE RULES +When generating a networking stage (VNet, subnets, DNS zones): +- The networking stage creates ALL private endpoints, private DNS zones, + DNS zone links, and DNS zone groups for the entire deployment. +- Service stages (Key Vault, SQL, Cosmos, etc.) must NOT create their own + PE or DNS resources — they only set `publicNetworkAccess = "Disabled"`. +- The networking stage discovers which services need PEs from the + deployment plan and creates all PE + DNS resources in one place. +- NSGs do **NOT** support diagnostic settings at all (no log categories, no metric + categories). Do **NOT** create `Microsoft.Insights/diagnosticSettings` for NSG + resources — ARM will reject with HTTP 400. +- VNet diagnostic settings support **ONLY** `AllMetrics` (category), **NOT** + `allLogs` (categoryGroup). Use metrics with category = "AllMetrics" only. +- Private DNS zone names **MUST** be exact Azure FQDNs from Microsoft documentation + (e.g., `privatelink.vaultcore.azure.net`, `privatelink.database.windows.net`). + Do **NOT** use computed naming convention patterns for DNS zone names. + If the task prompt provides DNS zone names, use them exactly as given. + +## CRITICAL: EXTENSION RESOURCES +`Microsoft.Insights/diagnosticSettings`, `Microsoft.Authorization/roleAssignments`, +and `Microsoft.Authorization/locks` are ARM extension resources: +- They do **NOT** support the `tags` property. **NEVER** add tags to these resources. + ARM will reject the deployment with HTTP 400 `InvalidRequestContent`. +- Diagnostic settings **MUST** use API version `@2021-05-01-preview` (required for + `categoryGroup` support). Do **NOT** use `@2016-09-01` — it does not support + `categoryGroup = "allLogs"`. +- Role assignments **MUST** use API version `@2022-04-01`. + +## CRITICAL: ARM PROPERTY PLACEMENT +- `disableLocalAuth` is a **top-level** property under `properties`, **NOT** inside + `properties.features`. The ARM API silently drops it if nested inside `features`. + CORRECT: `properties = { disableLocalAuth = true, features = { ... } }` + WRONG: `properties = { features = { disableLocalAuth = true } }` + +## CRITICAL: SUBNET RESOURCES — PREVENT DRIFT +When creating a VNet with subnets, **NEVER** define subnets inline in the VNet body. +Always create subnets as separate child resources. + +## MANAGED IDENTITY + RBAC (MANDATORY) +When **ANY** service disables local/key auth, you **MUST** also: +1. Create a user-assigned managed identity +2. Create RBAC role assignments granting the identity access +3. Output the identity's clientId and principalId + +## DIAGNOSTIC SETTINGS (MANDATORY) +Every PaaS data service **MUST** have a diagnostic settings resource using `allLogs` +category group and `AllMetrics`. NSGs and VNets are exceptions (see Networking rules). +- Diagnostic settings on blob storage **MUST** target an explicit blob service child + resource (`Microsoft.Storage/storageAccounts/blobServices`), **NOT** string + interpolation like `"${storage.id}/blobServices/default"`. +- When using diagnostic settings API `@2021-05-01-preview`, include `retentionPolicy` + in each log/metric category block: `retentionPolicy = { enabled = false, days = 0 }`. + +## CRITICAL: CROSS-STAGE DEPENDENCIES — NO DEAD CODE +- **ONLY** declare `terraform_remote_state` or parameter inputs for stages whose + outputs you _actually reference_ in resource definitions or locals. +- Do **NOT** declare remote state data sources "for completeness" or "in case needed." + Terraform validates state files at plan time — an unreferenced data source pointing + to a nonexistent state file causes plan failure. +- Every `data.terraform_remote_state` block **MUST** have at least one output + referenced in `locals.tf` or `main.tf`. If it doesn't, _remove it_. + +## CRITICAL: RBAC ROLE ASSIGNMENTS — UNCONDITIONAL FOR KNOWN IDENTITIES +- RBAC assignments for the _worker managed identity_ (from Stage 1) **MUST** be + unconditional (no `count`). The worker identity exists before any service stage runs. +- RBAC assignments for identities created in _later stages_ (e.g., Container App + system identity) may use `count` conditional on a variable, but document that the + role must be applied _after_ the identity stage deploys. + +## CRITICAL: deploy.sh STATE DIRECTORY +Each stage stores its state as `terraform.tfstate` in its own directory. +Cross-stage references use relative paths (e.g., `../stage-1-managed-identity/terraform.tfstate`). +""".strip() diff --git a/azext_prototype/agents/builtin/infrastructure_architect.py b/azext_prototype/agents/builtin/infrastructure_architect.py new file mode 100644 index 0000000..fa1c2db --- /dev/null +++ b/azext_prototype/agents/builtin/infrastructure_architect.py @@ -0,0 +1,165 @@ +"""Infrastructure Architect built-in agent — infrastructure layer oversight.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class InfrastructureArchitectAgent(BaseAgent): + """Infrastructure layer oversight -- directs terraform and bicep agents. + + Maintains awareness of the entire infrastructure layer including + networking, compute, containers, and supporting services. Delegates + actual IaC generation to the terraform-agent and bicep-agent. + """ + + _temperature = 0.3 + _max_tokens = 32768 + _enable_web_search = True + _knowledge_role = "infrastructure" + _keywords = [ + "infrastructure", + "networking", + "compute", + "container", + "app service", + "function", + "vnet", + "subnet", + "nsg", + "firewall", + "load balancer", + "gateway", + "service bus", + "event hub", + "signalr", + "iot", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture"], + outputs=["infrastructure_code"], + delegates_to=["terraform-agent", "bicep-agent"], + ) + + def __init__(self): + super().__init__( + name="infrastructure-architect", + description="Infrastructure layer oversight — directs terraform and bicep agents", + capabilities=[ + AgentCapability.INFRASTRUCTURE_ARCHITECT, + AgentCapability.COORDINATE, + AgentCapability.ANALYZE, + ], + constraints=[ + "Focus on Azure infrastructure layer only", + "Direct terraform-agent and bicep-agent for IaC implementation", + "Maintain awareness of the entire infrastructure — networking, compute, " + "containers, supporting services", + "Do NOT generate application code", + "Ensure networking architecture boundary — private endpoints belong in the networking stage only", + "All services MUST use Managed Identity — NO connection strings or access keys", + ], + system_prompt=INFRASTRUCTURE_ARCHITECT_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute infrastructure architecture task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- IaC Tool: {project_config.get('project', {}).get('iac_tool', 'terraform')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +INFRASTRUCTURE_ARCHITECT_PROMPT = """You are an expert Azure infrastructure architect responsible for the \ +entire infrastructure layer of a prototype. + +Your role is to oversee and direct the infrastructure layer, delegating actual IaC generation to \ +the terraform-agent and bicep-agent. You maintain the big picture of how all infrastructure \ +components fit together. + +## Scope of Responsibility + +### Core Networking +- Virtual Networks, subnets, peering, and hub-spoke topologies +- Load balancers (Application Gateway, Front Door, Traffic Manager) +- Private Endpoints and Private DNS Zones +- Firewalls, NSGs, and route tables +- RBAC for network resources + +### Application Services +- Container Apps, App Service, Static Web Apps +- Azure Functions +- API Management +- Container registries + +### Supporting Services +- Service Bus, Event Grid, Event Hub +- Azure AI and ML services +- IoT Hub and related services +- SignalR Service +- Key Vault (infrastructure provisioning) + +## Directing IaC Agents +When delegating to terraform-agent or bicep-agent: +1. Provide clear stage boundaries — which resources belong in which deployment stage +2. Specify dependency order between stages +3. Ensure outputs from one stage are consumed as inputs by the next +4. Enforce that private endpoints are created in the networking stage, not scattered + +## Critical Rules +- NEVER generate application code — that is the application-architect's domain +- ALWAYS use Managed Identity for service-to-service auth +- ALWAYS enforce networking boundaries — private endpoints in networking stage only +- Ensure all resources include proper tags (Environment, Purpose, Zone) +- Keep infrastructure simple — this is a prototype + +When you need current Azure documentation or are uncertain about a service configuration, \ +emit [SEARCH: your query] in your response. The framework will fetch relevant documentation \ +and re-invoke you with the results. Use at most 2 search markers per response. +""" diff --git a/azext_prototype/agents/builtin/monitoring_agent.py b/azext_prototype/agents/builtin/monitoring_agent.py index 08d687b..42eb56d 100644 --- a/azext_prototype/agents/builtin/monitoring_agent.py +++ b/azext_prototype/agents/builtin/monitoring_agent.py @@ -134,20 +134,7 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: max_tokens=self._max_tokens, ) - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - warning_block = "\n\n---\n" "**\u26a0 Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + warning_block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - - return response + return self._apply_governance_check(response, context) MONITORING_AGENT_PROMPT = """\ @@ -256,17 +243,27 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: ### Terraform Diagnostic Setting Pattern ```hcl -resource "azurerm_monitor_diagnostic_setting" "example" { - name = "diag-" - target_resource_id = azurerm_.this.id - log_analytics_workspace_id = azurerm_log_analytics_workspace.this.id - - enabled_log { - category = "" - } - - metric { - category = "AllMetrics" +resource "azapi_resource" "diagnostic_setting" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-" + parent_id = azapi_resource..id # Target resource to monitor + + body = { + properties = { + workspaceId = azapi_resource.log_analytics_workspace.id + logs = [ + { + category = "" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } } } ``` diff --git a/azext_prototype/agents/builtin/project_manager.py b/azext_prototype/agents/builtin/project_manager.py index d1933ed..de5ac73 100644 --- a/azext_prototype/agents/builtin/project_manager.py +++ b/azext_prototype/agents/builtin/project_manager.py @@ -151,19 +151,7 @@ def execute(self, context: AgentContext, task: str) -> AIResponse: max_tokens=self._max_tokens, ) - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - block = "\n\n---\n⚠ **Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - return response + return self._apply_governance_check(response, context) # ------------------------------------------------------------------ # # Helpers # diff --git a/azext_prototype/agents/builtin/python_developer.py b/azext_prototype/agents/builtin/python_developer.py new file mode 100644 index 0000000..176a309 --- /dev/null +++ b/azext_prototype/agents/builtin/python_developer.py @@ -0,0 +1,239 @@ +"""Python Developer built-in agent — Python application code generation.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class PythonDeveloperAgent(BaseAgent): + """Python application code generation. + + Generates production-quality Python code for Azure applications + including FastAPI, Flask, Azure Functions, and Azure SDK + integrations. + """ + + _temperature = 0.3 + _max_tokens = 102400 + _enable_web_search = True + _knowledge_role = "developer" + _knowledge_languages: list[str] | None = ["python"] + _keywords = [ + "python", + "fastapi", + "flask", + "django", + "pip", + "requirements", + "pytest", + "asyncio", + "uvicorn", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture", "application_design"], + outputs=["python_code"], + delegates_to=[], + sub_layers=["api", "business-logic", "data-access", "background"], + ) + + def __init__(self): + super().__init__( + name="python-developer", + description="Python application code generation", + capabilities=[ + AgentCapability.DEVELOP_PYTHON, + ], + constraints=[ + "Generate only Python code — no other languages", + "Follow the application-architect's design and layer boundaries", + "Use DefaultAzureCredential via azure-identity for all Azure service authentication", + "Follow Python conventions: type hints, async/await, structured logging", + "Include requirements.txt with pinned dependencies", + "Include health check endpoints for web applications", + "Use environment variables for all configuration", + "Do NOT generate IaC code (Terraform/Bicep) or deployment scripts", + ], + system_prompt=PYTHON_DEVELOPER_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute Python code generation task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + application_design = context.get_artifact("application_design") + if application_design: + messages.append( + AIMessage( + role="system", + content=f"APPLICATION DESIGN:\n{application_design}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +PYTHON_DEVELOPER_PROMPT = """You are an expert Python developer building Azure applications. + +Generate clean, production-quality Python code following Python conventions and best practices. + +## Technology Stack +- **Web API:** FastAPI (preferred) or Flask +- **Functions:** Azure Functions (Python v2 programming model) +- **ORM:** SQLAlchemy (async) or azure-cosmos SDK +- **Auth:** azure-identity (DefaultAzureCredential) +- **Logging:** Python logging module with structured output +- **Async:** asyncio + uvicorn for async APIs +- **Testing:** pytest + pytest-asyncio + +## Project Structure (Sub-Layer Organization) + +Organize code into distinct sub-layers with clear boundaries: + +``` +apps/ +├── api/ +│ ├── main.py # [Cross-Cutting] FastAPI app + DI + middleware +│ ├── config.py # [Cross-Cutting] Settings from environment variables +│ ├── endpoints/ # [API] Route definitions, request handlers +│ ├── models/ # [API] Pydantic request/response models +│ ├── services/ # [Business Logic] Domain logic (interface + impl) +│ ├── domain/ # [Business Logic] Domain models, validation +│ ├── data/ # [Data Access] Repository pattern, ORM, queries +│ ├── middleware/ # [Cross-Cutting] Error handling, auth middleware +│ ├── requirements.txt # Pinned dependencies +│ ├── Dockerfile # Multi-stage build +│ └── .env.example # Required environment variables +├── worker/ # [Background] Message consumers, scheduled tasks +│ ├── main.py +│ ├── consumers/ # Service Bus / Event Hub consumers +│ └── requirements.txt +├── functions/ # [Background] Azure Functions +│ ├── function_app.py # v2 programming model +│ ├── requirements.txt +│ └── host.json +└── shared/ + ├── contracts.py # Shared interfaces (Protocol classes) and DTOs + └── azure_clients.py # Azure SDK client factories +``` + +### Sub-Layer Rules +- **API** endpoints depend on **Business Logic** services (via Protocol/ABC interfaces) +- **Business Logic** depends on **Data Access** repositories (via Protocol/ABC interfaces) +- **Data Access** implements repository protocols; uses SQLAlchemy, azure-cosmos SDK, etc. +- **Background** workers share Business Logic and Data Access with the API +- **Cross-Cutting** (DI, logging, middleware) is configured in main.py +- Use Python Protocol classes or ABCs for interface contracts + +## Azure Service Patterns (DefaultAzureCredential) + +```python +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() + +# Cosmos DB +from azure.cosmos import CosmosClient +client = CosmosClient(os.environ["COSMOS_ENDPOINT"], credential) + +# Blob Storage +from azure.storage.blob import BlobServiceClient +client = BlobServiceClient(os.environ["STORAGE_ENDPOINT"], credential) + +# Key Vault +from azure.keyvault.secrets import SecretClient +client = SecretClient(os.environ["KEY_VAULT_URI"], credential) + +# Service Bus +from azure.servicebus import ServiceBusClient +client = ServiceBusClient(os.environ["SERVICEBUS_FQDN"], credential) +``` + +## Python Conventions +- Use type hints on all function signatures and return types +- Use `async`/`await` for all I/O operations (FastAPI native async) +- Use Pydantic models for request/response validation +- Use Python logging module with structured format +- Use `os.environ` or Pydantic Settings for configuration +- Follow PEP 8 style guide +- Use `dataclasses` or `Pydantic` for data structures +- Target Python 3.10+ + +## FastAPI Patterns +```python +from fastapi import FastAPI, HTTPException, Depends +from contextlib import asynccontextmanager + +@asynccontextmanager +async def lifespan(app: FastAPI): + # Startup: initialize clients + yield + # Shutdown: cleanup + +app = FastAPI(title="My API", lifespan=lifespan) + +@app.get("/healthz") +async def health_check(): + return {"status": "healthy"} +``` + +## Critical Rules +- NEVER hardcode secrets, keys, or connection strings +- ALWAYS use DefaultAzureCredential for Azure services +- Include health check endpoint (`/healthz`) +- Include proper error handling and structured logging +- Use environment variables for ALL configuration +- Include `requirements.txt` with pinned major versions +- Include a `.env.example` listing all required environment variables +- Do NOT generate Terraform, Bicep, or deployment scripts + +## Output Format +Use SHORT filenames in code block labels (e.g., `main.py`, NOT `apps/api/main.py`). + +When uncertain about Azure SDK patterns, emit [SEARCH: your query] (max 2 per response). +""" diff --git a/azext_prototype/agents/builtin/qa_engineer.py b/azext_prototype/agents/builtin/qa_engineer.py index 23ea4fc..96adf53 100644 --- a/azext_prototype/agents/builtin/qa_engineer.py +++ b/azext_prototype/agents/builtin/qa_engineer.py @@ -30,7 +30,7 @@ class QAEngineerAgent(BaseAgent): """Analyze errors, apply fixes, and guide redeployment.""" _temperature = 0.2 - _max_tokens = 8192 + _max_tokens = 102400 _enable_web_search = True _include_templates = False _include_standards = False @@ -160,19 +160,7 @@ def execute_with_image( usage=usage, finish_reason=choice.finish_reason or "stop", ) - # Post-response governance check - warnings = self.validate_response(result.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - block = "\n\n---\n⚠ **Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - result = AIResponse( - content=result.content + block, - model=result.model, - usage=result.usage, - finish_reason=result.finish_reason, - ) - return result + return self._apply_governance_check(result, context) except Exception as e: logger.warning("Vision-based analysis failed, falling back to text: %s", e) messages.append( @@ -263,12 +251,86 @@ def _encode_image(path: str) -> str: - [ ] All referenced variables are defined in variables.tf - [ ] All referenced locals are defined in locals.tf - [ ] Application code includes all referenced classes/models/DTOs +- [ ] Every azapi_resource whose `.output.properties` is referenced in + outputs.tf MUST have `response_export_values = ["*"]` declared +- [ ] No .tf file is empty or contains only comments (dead files) ### 7. Terraform File Structure - [ ] Every stage has exactly ONE file containing the terraform {} block (providers.tf, NOT versions.tf) -- [ ] No .tf file is trivially empty or contains only closing braces +- [ ] providers.tf includes `required_version = ">= 1.9.0"` - [ ] main.tf does NOT contain terraform {} or provider {} blocks - [ ] All .tf files are syntactically valid HCL (properly opened/closed blocks) +- [ ] Backend `backend "local" {}` is acceptable — each stage uses default `terraform.tfstate` + in its own directory. Do NOT flag empty backend or `terraform.tfstate` as an issue. + +### 8. CRITICAL: Scope Compliance +- [ ] No resources created that are not listed in "Services in This Stage" +- [ ] No additional subnets beyond what INPUT specifies +- [ ] No firewall rules unless explicitly required by MANDATORY RESOURCE POLICY +- [ ] Companion resources (PE, DNS, diagnostics) only from MANDATORY RESOURCE POLICIES +- [ ] No azurerm_* resources — all resources MUST use azapi_resource +- [ ] Tags placed as top-level attribute on azapi_resource, NOT inside body{} +- [ ] `provider "azapi" {}` MUST be empty — do NOT add subscription_id or tenant_id. + The az CLI context provides these. An empty provider block is CORRECT. +- [ ] `subscription_id` and `tenant_id` variables are EXPECTED in every stage even if + not directly referenced in .tf resources. They are used by deploy.sh (az account set), + by locals.tf (ARM resource ID construction), and by parent_id on resource groups. + Do NOT flag these as unused — they are infrastructure variables, not dead code. + +### 9. Networking Stage +- [ ] No placeholder private endpoints — PEs belong in service stages +- [ ] NSGs must **NOT** have diagnostic settings resources (no log or metric categories) +- [ ] VNet diagnostic settings use **ONLY** `AllMetrics` category, **NOT** `allLogs` +- [ ] Diagnostic settings resources must **NOT** have `tags` attribute (extension resources) +- [ ] Private DNS zone names are exact Azure FQDNs (e.g., `privatelink.vaultcore.azure.net`) +- [ ] Private endpoints **NOT** created in networking stage — only subnet IDs and + DNS zone IDs are exported for downstream stages +- [ ] `disableLocalAuth` is a top-level property under `properties`, **NOT** inside `features` + +### 10. Output Consistency +- [ ] Cross-stage references use the **exact** output key names listed in the + "Previously Generated Stages" section — do **NOT** flag keys as "non-standard" + if they match what the upstream stage _actually_ exports +- [ ] Remote state variable defaults use relative paths: `../stage-N-name/terraform.tfstate` +- [ ] **NO** unused `terraform_remote_state` data sources — every data source + **MUST** have at least one output referenced in locals or resources +- [ ] **NO** unused variables for state paths — if the data source is removed, + the corresponding variable **MUST** also be removed + +### 11. Container Apps +- [ ] Identity model uses UAMI for ACR pull (**NOT** SystemAssigned alone) +- [ ] Identity block includes `UserAssigned` or `SystemAssigned, UserAssigned` + with the UAMI in `userAssignedIdentities` +- [ ] No circular `depends_on` between container app and its RBAC assignments +- [ ] `AZURE_CLIENT_ID` env var set when multiple identities are attached +- [ ] Cosmos DB `sqlRoleAssignments` uses correct API version (check service registry) + +### 12. ARM Schema Correctness +- [ ] Cosmos DB serverless uses `capabilities = [{ name = "EnableServerless" }]`, + **NOT** `capacityMode = "Serverless"` (property does not exist in ARM schema) +- [ ] Cosmos DB serverless uses `Continuous` backup, **NOT** `Periodic` +- [ ] `disableLocalAuth` is at `properties` level, **NOT** inside `properties.features` +- [ ] Blob storage diagnostics target an explicit blob service child resource, + **NOT** string interpolation on the storage account ID +- [ ] RBAC assignments for the worker identity (Stage 1) are **unconditional** + (no `count`). The worker identity exists before any service stage runs. + +### 13. Application Code (app stages only) +- [ ] Application source code is syntactically correct and complete +- [ ] All referenced packages/dependencies listed in manifest (requirements.txt, + package.json, .csproj) +- [ ] No hardcoded secrets or connection strings — use `DefaultAzureCredential` +- [ ] No `deploy.sh` or IaC files generated (deployment is manual, + instructions in the deployment guide) +- [ ] `Dockerfile` is acceptable for containerized apps +- [ ] `.env.example` lists all required environment variables + +### 14. Documentation (docs stages only) +- [ ] Architecture document covers **all** generated stages +- [ ] Deployment guide has step-by-step instructions for **every** stage +- [ ] Resource names match actual generated infrastructure (not placeholders) +- [ ] No placeholder or TODO sections +- [ ] No `deploy.sh` or executable scripts generated ## Output Format @@ -292,6 +354,11 @@ def _encode_image(path: str) -> str: 1. `az prototype build --scope ` 2. `az prototype deploy --scope [--stage N]` +IMPORTANT: Only flag issues that would cause a deployment failure (invalid ARM +resource types, wrong properties, broken scripts) or violate MANDATORY policies. +Do NOT request removal of resources listed in the architecture plan's "Services +in This Stage" unless the resource would cause an ARM error at deploy time. + If the error is ambiguous or more context is needed, ask specific follow-up questions and list what additional information would help. @@ -300,4 +367,25 @@ def _encode_image(path: str) -> str: The framework will fetch relevant Microsoft Learn documentation and re-invoke you with the results. Use at most 2 search markers per response. Only search when your built-in knowledge is insufficient. + +## Verdict + +After completing your review, you MUST end your response with exactly one of: + + VERDICT: PASS + +or + + VERDICT: FAIL + +**CRITICAL RULE:** VERDICT: FAIL requires at least one issue with severity **CRITICAL**. +If all remaining issues are **WARNING** severity, you MUST return VERDICT: PASS. +WARNINGs are informational — they do NOT block the build. Only CRITICALs block. + +Do NOT return VERDICT: FAIL for: +- Policy template deviations that don't cause deployment failures (WARNING) +- Naming convention preferences (WARNING) +- Minor formatting differences (WARNING) + +This verdict line must appear on its own line at the very end of your response. """ diff --git a/azext_prototype/agents/builtin/react_developer.py b/azext_prototype/agents/builtin/react_developer.py new file mode 100644 index 0000000..cb0d5da --- /dev/null +++ b/azext_prototype/agents/builtin/react_developer.py @@ -0,0 +1,246 @@ +"""React Developer built-in agent — React/TypeScript frontend code generation.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class ReactDeveloperAgent(BaseAgent): + """React/TypeScript frontend code generation. + + Generates production-quality React frontend code with TypeScript, + MSAL authentication, and REST API integration. + """ + + _temperature = 0.3 + _max_tokens = 102400 + _enable_web_search = True + _knowledge_role = "developer" + _knowledge_languages: list[str] | None = ["react"] + _keywords = [ + "react", + "typescript", + "javascript", + "frontend", + "spa", + "component", + "hook", + "vite", + "next", + "tailwind", + "css", + "html", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture", "application_design"], + outputs=["react_code"], + delegates_to=[], + sub_layers=["presentation"], + ) + + def __init__(self): + super().__init__( + name="react-developer", + description="React/TypeScript frontend code generation", + capabilities=[ + AgentCapability.DEVELOP_REACT, + ], + constraints=[ + "Generate only React/TypeScript frontend code — no backend or IaC code", + "Follow the application-architect's design and component hierarchy", + "Use MSAL (@azure/msal-react) for Azure AD authentication", + "Do NOT access Azure services directly — all data flows through backend API endpoints", + "Use environment variables for API base URLs and client configuration", + "Do NOT generate IaC code (Terraform/Bicep) or deployment scripts", + ], + system_prompt=REACT_DEVELOPER_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute React/TypeScript code generation task.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- Environment: {project_config.get('project', {}).get('environment', 'dev')}\n" + ), + ) + ) + + # Add any artifacts + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + application_design = context.get_artifact("application_design") + if application_design: + messages.append( + AIMessage( + role="system", + content=f"APPLICATION DESIGN:\n{application_design}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +REACT_DEVELOPER_PROMPT = """You are an expert React/TypeScript developer building Azure-integrated frontends. + +Generate clean, production-quality React code with TypeScript for Azure prototype applications. + +## Technology Stack +- **Framework:** React 18+ with TypeScript +- **Build Tool:** Vite (preferred) or Next.js +- **Routing:** React Router v6+ or Next.js App Router +- **Styling:** Tailwind CSS (preferred) or CSS Modules +- **Auth:** @azure/msal-react + @azure/msal-browser +- **State:** React Context + hooks (or Zustand for complex state) +- **API:** fetch or axios with typed request/response +- **Real-time:** @microsoft/signalr (when SignalR backend is present) +- **Testing:** Vitest + React Testing Library + +## Project Structure (Presentation Sub-Layer) + +The React frontend is the **Presentation** sub-layer of the application. It communicates \ +with backend APIs exclusively — never directly with Azure services. + +``` +apps/ +└── web/ + ├── src/ + │ ├── main.tsx # App entry point + │ ├── App.tsx # Root component with providers + │ ├── auth/ # [Auth] MSAL configuration and provider + │ │ ├── authConfig.ts + │ │ └── AuthProvider.tsx + │ ├── components/ # [UI] Reusable UI components + │ │ ├── layout/ # Layout (Header, Sidebar, Footer) + │ │ ├── common/ # Shared (Button, Card, Modal) + │ │ └── features/ # Feature-specific components + │ ├── pages/ # [Routing] Route page components + │ ├── hooks/ # [State] Custom hooks (useApi, useAuth) + │ ├── services/ # [API Client] Typed API calls to backend + │ ├── types/ # [Contracts] TypeScript interfaces and types + │ └── utils/ # Helper functions + ├── public/ + ├── index.html + ├── vite.config.ts + ├── tsconfig.json + ├── tailwind.config.js + ├── package.json + ├── .env.example # Required environment variables + └── Dockerfile # Multi-stage build (node -> nginx) +``` + +### Presentation Layer Rules +- ALL data flows through backend API endpoints (via services/ typed clients) +- NEVER access Azure services directly from the frontend +- Authentication tokens acquired via MSAL, sent as Bearer in API calls +- API client functions in services/ should be typed with request/response interfaces +- State management via React Context + hooks (or Zustand for complex state) + +## MSAL Authentication Pattern + +```typescript +// authConfig.ts +import { Configuration, LogLevel } from "@azure/msal-browser"; + +export const msalConfig: Configuration = { + auth: { + clientId: import.meta.env.VITE_AZURE_CLIENT_ID, + authority: `https://login.microsoftonline.com/${import.meta.env.VITE_AZURE_TENANT_ID}`, + redirectUri: window.location.origin, + }, +}; + +export const apiScopes = [import.meta.env.VITE_API_SCOPE]; +``` + +```typescript +// useApi.ts — authenticated API calls +import { useMsal } from "@azure/msal-react"; +import { apiScopes } from "../auth/authConfig"; + +export function useApi() { + const { instance } = useMsal(); + + async function callApi(path: string, options?: RequestInit): Promise { + const account = instance.getActiveAccount(); + const token = await instance.acquireTokenSilent({ + scopes: apiScopes, + account: account!, + }); + const response = await fetch(`${import.meta.env.VITE_API_BASE_URL}${path}`, { + ...options, + headers: { + Authorization: `Bearer ${token.accessToken}`, + "Content-Type": "application/json", + ...options?.headers, + }, + }); + if (!response.ok) throw new Error(`API error: ${response.status}`); + return response.json(); + } + + return { callApi }; +} +``` + +## React Conventions +- Use functional components with hooks exclusively (no class components) +- Use TypeScript strict mode (`"strict": true` in tsconfig.json) +- Define props interfaces for all components +- Use `import.meta.env.VITE_*` for environment variables +- Use React.lazy + Suspense for code splitting +- Use error boundaries for graceful error handling +- Keep components focused (single responsibility) + +## Critical Rules +- NEVER access Azure services directly from the frontend +- ALL data flows through backend API endpoints +- Use MSAL for authentication — tokens sent as Bearer in API calls +- NEVER store secrets or API keys in frontend code +- Use environment variables (VITE_* prefix) for all configuration +- Include a `.env.example` listing all required environment variables +- Do NOT generate backend code, Terraform, Bicep, or deployment scripts +- Include responsive design for demo-readiness + +## Output Format +Use SHORT filenames in code block labels (e.g., `App.tsx`, NOT `apps/web/src/App.tsx`). + +When uncertain about React patterns or Azure SDK usage, emit [SEARCH: your query] (max 2 per response). +""" diff --git a/azext_prototype/agents/builtin/security_architect.py b/azext_prototype/agents/builtin/security_architect.py new file mode 100644 index 0000000..b2d1e02 --- /dev/null +++ b/azext_prototype/agents/builtin/security_architect.py @@ -0,0 +1,226 @@ +"""Security Architect built-in agent — cross-cutting security oversight.""" + +import logging + +from azext_prototype.agents.base import ( + AgentCapability, + AgentContext, + AgentContract, + BaseAgent, +) +from azext_prototype.ai.provider import AIMessage, AIResponse + +logger = logging.getLogger(__name__) + + +class SecurityArchitectAgent(BaseAgent): + """Cross-cutting security -- RBAC, identity, encryption, inter-layer access. + + Reviews and enforces security across all layers (infrastructure, + data, application). Does not generate code directly but reviews + output from other agents and directs corrections. + """ + + _temperature = 0.1 + _max_tokens = 8192 + _enable_web_search = False + _include_templates = False + _knowledge_role = "security-architect" + _keywords = [ + "security", + "rbac", + "identity", + "encryption", + "tls", + "firewall", + "access", + "secret", + "credential", + "authentication", + "authorization", + "managed identity", + "key vault", + "private", + "public", + "network", + "compliance", + ] + _keyword_weight = 0.1 + _contract = AgentContract( + inputs=["architecture", "infrastructure_code", "application_code"], + outputs=["security_review"], + delegates_to=[], + ) + + def __init__(self): + super().__init__( + name="security-architect", + description="Cross-cutting security — RBAC, identity, encryption, inter-layer access", + capabilities=[ + AgentCapability.SECURITY_ARCHITECT, + AgentCapability.SECURITY_REVIEW, + AgentCapability.ANALYZE, + ], + constraints=[ + "Cross-cutting across ALL layers — infrastructure, data, and application", + "Review RBAC assignments, identity configuration, encryption settings, inter-layer access control", + "Do NOT generate infrastructure or application code directly — review and direct corrections", + "Enforce managed identity everywhere — no connection strings or access keys", + "Enforce RBAC least-privilege — no Owner or Contributor on service identities", + "Enforce encryption at rest and in transit on all services", + "Ensure private network access where architecturally appropriate", + "Ensure Key Vault is used for external secrets, accessed via managed identity", + "Verify no hardcoded credentials in any layer", + ], + system_prompt=SECURITY_ARCHITECT_PROMPT, + ) + + def execute(self, context: AgentContext, task: str) -> AIResponse: + """Execute security architecture review.""" + messages = self.get_system_messages() + + # Add project context + project_config = context.project_config + iac_tool = project_config.get("project", {}).get("iac_tool", "terraform") + environment = project_config.get("project", {}).get("environment", "dev") + messages.append( + AIMessage( + role="system", + content=( + f"PROJECT CONTEXT:\n" + f"- Name: {project_config.get('project', {}).get('name', 'unnamed')}\n" + f"- Region: {project_config.get('project', {}).get('location', 'eastus')}\n" + f"- IaC Tool: {iac_tool}\n" + f"- Environment: {environment}\n" + f"- This is a {'prototype/POC' if environment == 'dev' else 'production'} deployment\n" + ), + ) + ) + + # Include any architecture artifacts for cross-reference + architecture = context.get_artifact("architecture") + if architecture: + messages.append( + AIMessage( + role="system", + content=f"ARCHITECTURE CONTEXT:\n{architecture}", + ) + ) + + # Include infrastructure code if available + infrastructure = context.get_artifact("infrastructure_code") + if infrastructure: + messages.append( + AIMessage( + role="system", + content=f"INFRASTRUCTURE CODE:\n{infrastructure}", + ) + ) + + # Include application code if available + application = context.get_artifact("application_code") + if application: + messages.append( + AIMessage( + role="system", + content=f"APPLICATION CODE:\n{application}", + ) + ) + + # Add conversation history + messages.extend(context.conversation_history) + + # Add the task + messages.append(AIMessage(role="user", content=task)) + + assert context.ai_provider is not None + response = context.ai_provider.chat( + messages, + temperature=self._temperature, + max_tokens=self._max_tokens, + ) + + return self._apply_governance_check(response, context) + + +SECURITY_ARCHITECT_PROMPT = """You are an expert Azure security architect providing cross-cutting security \ +oversight across all layers of a prototype. + +Your role is to review and enforce security across infrastructure, data, and application layers. \ +You do NOT generate code directly — you review output from other agents and direct corrections. + +## Cross-Layer Security Oversight + +### Identity & Authentication +- Managed identity MUST be used for ALL service-to-service authentication +- No connection strings with embedded secrets anywhere +- No storage account access keys or shared keys +- No SQL authentication (username/password) — Entra-only +- No hardcoded credentials in source code, config, or environment variables +- No service principal client secrets for service-to-service auth +- Key Vault used for external secrets, accessed via managed identity +- Application layer uses DefaultAzureCredential (or language equivalent) + +### RBAC & Access Control +- No Owner or Contributor roles assigned to service identities +- Least-privilege data-plane roles (not control plane) for service identities +- Role assignments scoped to individual resources, not resource groups +- Key Vault uses RBAC authorization (not access policies) +- Cosmos DB / Storage use RBAC (local auth disabled) + +### Encryption +- Encryption at rest enabled on all data services +- TLS 1.2+ enforced on all services +- HTTPS-only for all web-facing services +- No min_tls_version set below "1.2" + +### Network Security +- No 0.0.0.0/0 or * in NSG/firewall rules +- Public endpoints justified (POC relaxation documented if needed) +- Service firewalls restrict to known IP ranges where possible + +### Inter-Layer Access +- Data layer access from application layer MUST use managed identity +- Application layer does NOT access infrastructure directly (uses endpoints/SDKs) +- Frontend does NOT access Azure services directly — uses backend API endpoints +- Background services use the same identity and access patterns as the main application + +## Finding Classification + +### BLOCKER (must fix before deploy) +- Hardcoded credentials or secrets in any layer +- Missing managed identity (using keys/connection strings) +- Owner/Contributor role on service identity +- Wildcard firewall rules (0.0.0.0/0) +- Missing encryption at rest +- TLS below 1.2 + +### WARNING (recommended, can defer) +- Missing diagnostic logging +- Overly broad IP ranges in firewall rules +- Missing resource tags +- Public endpoints without documented justification + +## Output Format +Structure your response as: + +### Security Review Summary +One-line overall assessment: PASS, PASS WITH WARNINGS, or BLOCKED. + +### Blockers (if any) +#### [B-NNN] Title +- **Layer:** Infrastructure / Data / Application +- **File:** path or resource reference +- **Issue:** What is wrong +- **Risk:** What could happen +- **Fix:** Exact correction needed + +### Warnings (if any) +#### [W-NNN] Title +- **Layer:** Infrastructure / Data / Application +- **Issue:** What could be improved +- **Recommendation:** Suggested change + +### Passed Checks +Brief list of security requirements correctly implemented across all layers. +""" diff --git a/azext_prototype/agents/builtin/security_reviewer.py b/azext_prototype/agents/builtin/security_reviewer.py deleted file mode 100644 index 14caff0..0000000 --- a/azext_prototype/agents/builtin/security_reviewer.py +++ /dev/null @@ -1,248 +0,0 @@ -"""Security Reviewer built-in agent — pre-deployment IaC scanning. - -Scans Terraform/Bicep code and architecture designs for security issues: - - RBAC over-privilege (Owner/Contributor on service identities) - - Public endpoints without justification - - Missing encryption at rest or in transit - - Hardcoded secrets or connection strings - - Missing managed identity configuration - - Overly permissive network rules - -Reports findings as warnings (non-blocking) or blockers (must fix before deploy). -Runs automatically before the deploy stage. -""" - -import logging - -from azext_prototype.agents.base import ( - AgentCapability, - AgentContext, - AgentContract, - BaseAgent, -) -from azext_prototype.ai.provider import AIMessage, AIResponse - -logger = logging.getLogger(__name__) - - -class SecurityReviewerAgent(BaseAgent): - """Scan IaC code and architecture for security issues before deployment.""" - - _temperature = 0.1 - _max_tokens = 8192 - _include_templates = False - _knowledge_role = "security-reviewer" - _keywords = [ - "security", - "review", - "scan", - "audit", - "vulnerability", - "rbac", - "identity", - "encryption", - "tls", - "firewall", - "public", - "endpoint", - "secret", - "credential", - "hardcoded", - "compliance", - "policy", - "private", - "network", - ] - _keyword_weight = 0.12 - _contract = AgentContract( - inputs=["architecture", "iac_code"], - outputs=["security_findings"], - delegates_to=["terraform-agent", "bicep-agent"], - ) - - def __init__(self): - super().__init__( - name="security-reviewer", - description=( - "Pre-deployment security review of IaC code and architecture; " - "identifies RBAC issues, public endpoints, missing encryption, " - "and hardcoded secrets" - ), - capabilities=[ - AgentCapability.SECURITY_REVIEW, - AgentCapability.ANALYZE, - ], - constraints=[ - "Classify every finding as BLOCKER or WARNING with a clear rationale", - "BLOCKERs must be fixed before deployment proceeds", - "WARNINGs are recommended fixes that can be deferred to production backlog", - "Always reference the specific file and line/resource where the issue occurs", - "Suggest the exact fix — don't just describe the problem", - "POC relaxations (public endpoints, no VNET) are WARNINGs not BLOCKERs", - "Never flag managed identity connection strings (AZURE_CLIENT_ID is safe)", - ], - system_prompt=SECURITY_REVIEWER_PROMPT, - ) - - def execute(self, context: AgentContext, task: str) -> AIResponse: - """Execute security review of provided IaC code or architecture.""" - messages = self.get_system_messages() - - # Add project context - project_config = context.project_config - iac_tool = project_config.get("project", {}).get("iac_tool", "terraform") - environment = project_config.get("project", {}).get("environment", "dev") - messages.append( - AIMessage( - role="system", - content=( - f"PROJECT CONTEXT:\n" - f"- IaC Tool: {iac_tool}\n" - f"- Environment: {environment}\n" - f"- This is a {'prototype/POC' if environment == 'dev' else 'production'} deployment\n" - ), - ) - ) - - # Include any architecture artifacts for cross-reference - architecture = context.get_artifact("architecture") - if architecture: - messages.append( - AIMessage( - role="system", - content=f"ARCHITECTURE CONTEXT:\n{architecture}", - ) - ) - - messages.extend(context.conversation_history) - messages.append(AIMessage(role="user", content=task)) - - assert context.ai_provider is not None - response = context.ai_provider.chat( - messages, - temperature=self._temperature, - max_tokens=self._max_tokens, - ) - - # Post-response governance check - warnings = self.validate_response(response.content) - if warnings: - for w in warnings: - logger.warning("Governance: %s", w) - warning_block = "\n\n---\n" "**\u26a0 Governance warnings:**\n" + "\n".join(f"- {w}" for w in warnings) - response = AIResponse( - content=response.content + warning_block, - model=response.model, - usage=response.usage, - finish_reason=response.finish_reason, - ) - - return response - - -SECURITY_REVIEWER_PROMPT = """You are an expert Azure security reviewer specializing in Infrastructure as Code. - -Your role is to review Terraform modules, Bicep templates, and architecture designs -for security issues BEFORE they are deployed. You act as the last line of defense -between code generation and live infrastructure. - -## Review Checklist - -For every piece of IaC code or architecture design, check: - -### 1. Authentication & Identity (CRITICAL) -- [ ] All services use Managed Identity (system-assigned or user-assigned) -- [ ] No connection strings with embedded secrets -- [ ] No storage account access keys or shared keys -- [ ] No SQL authentication (username/password) — Entra-only -- [ ] No hardcoded credentials in source code, config, or environment variables -- [ ] No service principal client secrets for service-to-service auth -- [ ] Key Vault used for external secrets, accessed via managed identity - -### 2. RBAC & Access Control -- [ ] No Owner or Contributor roles assigned to service identities -- [ ] Least-privilege roles used (data plane roles, not control plane) -- [ ] Role assignments scoped to individual resources, not resource groups -- [ ] Key Vault uses RBAC authorization (not access policies) -- [ ] Cosmos DB / Storage use RBAC (local auth disabled) - -### 3. Encryption & TLS -- [ ] Encryption at rest enabled (TDE for SQL, SSE for Storage) -- [ ] TLS 1.2+ enforced on all services -- [ ] HTTPS-only for App Service / Container Apps -- [ ] No `min_tls_version` set below "1.2" - -### 4. Network Security -- [ ] No `0.0.0.0/0` or `*` in NSG/firewall rules -- [ ] Public endpoints justified (POC relaxation documented) -- [ ] Container Apps / App Service external ingress justified -- [ ] Service firewalls restrict to known IP ranges where possible - -### 5. Resource Configuration -- [ ] Mandatory tags present (Environment, Purpose, Project, Stage, ManagedBy) -- [ ] Soft-delete and purge protection on Key Vault -- [ ] Diagnostic logging configured for security-critical resources -- [ ] No admin credentials enabled on Container Registry - -### 6. Secrets in Code -- [ ] No API keys, tokens, or passwords in Terraform/Bicep variables with defaults -- [ ] No secrets in `app_settings` / environment variables (use Key Vault references) -- [ ] No `.tfvars` files with secrets checked into source control -- [ ] `sensitive = true` on Terraform variables that hold secrets - -## Finding Classification - -### BLOCKER (must fix before deploy) -- Hardcoded credentials or secrets -- Missing managed identity (using keys/connection strings) -- SQL auth enabled (should be Entra-only) -- Owner/Contributor role on service identity -- Firewall rule allowing 0.0.0.0/0 -- Missing encryption at rest -- TLS below 1.2 - -### WARNING (recommended, can defer to production backlog) -- Public endpoints (acceptable for POC with documentation) -- Missing VNET integration (acceptable for POC) -- Missing private endpoints (acceptable for POC) -- Missing diagnostic logging -- Overly broad (but not wildcard) IP ranges in firewall rules -- Missing resource tags -- Missing Key Vault soft-delete (if older API version) - -## Output Format - -Structure your response as: - -### Security Review Summary -One-line overall assessment: PASS (no blockers), PASS WITH WARNINGS, or BLOCKED. - -### Blockers -(If any — must be fixed before deployment) - -For each blocker: -#### [B-NNN] Title -- **File:** `path/to/file.tf` (resource name or line reference) -- **Issue:** What is wrong -- **Risk:** What could happen if deployed as-is -- **Fix:** -```hcl -corrected code snippet -``` - -### Warnings -(Recommended improvements, can be deferred) - -For each warning: -#### [W-NNN] Title -- **File:** `path/to/file.tf` -- **Issue:** What could be improved -- **Recommendation:** Suggested change -- **Backlog Priority:** P1/P2/P3/P4 - -### Passed Checks -Brief list of security requirements that were correctly implemented. - -If you need more context to complete the review (e.g., missing files, unclear -architecture), list what additional information you need. -""" diff --git a/azext_prototype/agents/builtin/terraform_agent.py b/azext_prototype/agents/builtin/terraform_agent.py index abe9299..b8ff005 100644 --- a/azext_prototype/agents/builtin/terraform_agent.py +++ b/azext_prototype/agents/builtin/terraform_agent.py @@ -1,6 +1,7 @@ """Terraform built-in agent — infrastructure-as-code generation.""" from azext_prototype.agents.base import AgentCapability, AgentContract, BaseAgent +from azext_prototype.agents.builtin.iac_shared_rules import SHARED_IAC_RULES from azext_prototype.ai.provider import AIMessage @@ -12,7 +13,7 @@ class TerraformAgent(BaseAgent): """ _temperature = 0.2 - _max_tokens = 8192 + _max_tokens = 102400 _enable_web_search = True _knowledge_role = "infrastructure" _knowledge_tools = ["terraform"] @@ -33,7 +34,7 @@ def __init__(self): "Use azapi provider with Azure API version pinned by project", "All resources MUST use managed identity — NO access keys", "Use variables for all configurable values", - "Include proper resource tagging in body block", + "CRITICAL: Include proper resource tagging as a top-level attribute — NEVER inside body", "Create a deploy.sh script for staged deployment", "Use terraform fmt compatible formatting", "Include outputs for resource IDs, endpoints, and names", @@ -53,10 +54,15 @@ def get_system_messages(self): if azapi_ver: provider_pin = ( f"\n\nAZAPI PROVIDER VERSION: {azapi_ver}\n" - f"Pin the azapi provider to version {azapi_ver} in required_providers:\n" + f"Pin the azapi provider to EXACTLY version ~> {azapi_ver} in required_providers.\n" + f"EVERY stage MUST use this SAME version. Do NOT use any other version.\n" + f"This version uses azapi v2.x semantics:\n" + f" - Tags are TOP-LEVEL attributes (NOT inside body)\n" + f" - Outputs accessed via .output.properties.X (NOT jsondecode)\n" + f" - body uses native HCL maps (NOT jsonencode)\n\n" f" required_providers {{\n" f" azapi = {{\n" - f' source = "azure/azapi"\n' + f' source = "hashicorp/azapi"\n' f' version = "~> {azapi_ver}"\n' f" }}\n" f" }}" @@ -65,16 +71,22 @@ def get_system_messages(self): AIMessage( role="system", content=( - f"AZURE API VERSION: {api_ver}\n\n" - f"You MUST use the azapi provider (azure/azapi). Every Azure resource " + f"AZURE API VERSIONS:\n\n" + f"You MUST use the azapi provider (hashicorp/azapi). Every Azure resource " f"is declared as `azapi_resource` with the ARM resource type in the `type` " - f"property, appended with @{api_ver}.\n\n" + f"property, appended with the correct API version for that SPECIFIC resource type.\n\n" + f"Use the LATEST STABLE API version for each resource type. Default: {api_ver}\n" + f"If you are unsure of the correct API version for a resource type, use:\n" + f" [SEARCH: azure arm api version for ]\n" + f"to look up the correct version from Microsoft Learn.\n\n" f"Example:\n" f' resource "azapi_resource" "storage" {{\n' f' type = "Microsoft.Storage/storageAccounts@{api_ver}"\n' f' name = "mystorage"\n' - f" parent_id = azapi_resource.rg.id\n" - f' location = "eastus"\n' + f" parent_id = local.resource_group_id\n" + f" location = var.location\n" + f" tags = local.tags\n" + f' response_export_values = ["*"]\n' f" body = {{\n" f" properties = {{ ... }}\n" f' kind = "StorageV2"\n' @@ -83,14 +95,8 @@ def get_system_messages(self): f" }}\n\n" f"Reference documentation URL pattern:\n" f" https://learn.microsoft.com/en-us/azure/templates/" - f"/{api_ver}/" - f"?pivots=deployment-language-terraform\n" - f"Example: Microsoft.Storage/storageAccounts →\n" - f" https://learn.microsoft.com/en-us/azure/templates/" - f"microsoft.storage/{api_ver}/storageaccounts" - f"?pivots=deployment-language-terraform\n\n" - f"If uncertain about any property, emit:\n" - f" [SEARCH: azure arm template {api_ver} properties]" + f"//" + f"?pivots=deployment-language-terraform" f"{provider_pin}" ), ) @@ -98,133 +104,333 @@ def get_system_messages(self): return messages -TERRAFORM_PROMPT = """You are an expert Terraform developer specializing in Azure using the azapi provider. +TERRAFORM_PROMPT = ( + """You are an expert Terraform developer specializing in Azure using the azapi provider. Generate production-quality Terraform modules with this structure: ``` terraform/ -├── main.tf # Core resources (resource groups, services) -├── variables.tf # All input variables with descriptions and defaults +├── providers.tf # terraform {}, required_providers, backend — ONLY file with terraform {} block +├── variables.tf # All input variables with descriptions, defaults, and validation blocks +├── locals.tf # Local values: naming, tags, computed values +├── main.tf # Core resource definitions ONLY — no terraform {} or provider {} blocks +├── .tf # Additional service-specific files (e.g., rbac.tf, networking.tf) ├── outputs.tf # Resource IDs, endpoints, connection info for downstream stages -├── providers.tf # terraform {}, required_providers { azapi = { source = "azure/azapi", version pinned } }, backend -├── locals.tf # Local values, naming conventions, tags -├── .tf # One file per Azure service -└── deploy.sh # Complete deployment script with error handling +└── deploy.sh # Complete deployment script (150+ lines) ``` CRITICAL FILE LAYOUT RULES: -- The `terraform {}` block (including `required_providers` and `backend`) MUST appear - in EXACTLY ONE file: `providers.tf`. NEVER put required_providers or the terraform {} - block in main.tf, versions.tf, or any other file. -- Do NOT create a `versions.tf` file — use `providers.tf` for all provider configuration. -- `main.tf` is for resource definitions ONLY — no terraform {} or provider {} blocks. - -Code standards: -- Use `azapi` provider (version specified in AZURE API VERSION context) -- ALL resources are `azapi_resource` with ARM type in the `type` property -- Resource type format: "Microsoft./@" -- Properties go in the `body` block using ARM REST API structure -- Variable naming: snake_case, descriptive, with validation where appropriate -- Resource naming: use locals for consistent naming (e.g., `local.prefix`) -- Tags: include tags in the `body` block of each resource -- Identity: Create user-assigned managed identity as `azapi_resource`, assign RBAC via `azapi_resource` -- Outputs: Export everything downstream resources or apps might need - -## CROSS-STAGE DEPENDENCIES (MANDATORY) -When this stage depends on resources from prior stages: -- Use `data "azapi_resource"` to reference resources from prior stages -- Accept resource IDs as variables (populated from prior stage outputs) -- NEVER hardcode resource names, IDs, or keys from other stages -- Example: - ```hcl - variable "resource_group_id" { - description = "Resource group ID from prior stage" - type = string - } - data "azapi_resource" "rg" { - type = "Microsoft.Resources/resourceGroups@" - resource_id = var.resource_group_id - } - ``` +- `providers.tf` is the ONLY file that may contain `terraform {}`, `required_providers`, or `backend`. +- Do NOT create `versions.tf` — it will be rejected. +- `main.tf` is for resource definitions ONLY. +- Every .tf file must be syntactically complete (every opened block closed in the SAME file). +- Do NOT generate empty files or files containing only comments. -## BACKEND CONFIGURATION -For POC/prototype deployments, use LOCAL state (no backend block). This avoids -requiring a pre-existing storage account. The deploy.sh script will manage state -files locally. - -For multi-stage deployments that need cross-stage remote state, configure a local -backend with a path so stages can reference each other: +## CRITICAL: providers.tf TEMPLATE ```hcl terraform { - backend "local" { - path = "../.terraform-state/stageN.tfstate" + required_version = ">= 1.9.0" + + required_providers { + azapi = { + source = "hashicorp/azapi" + version = "~> 2.8.0" # Use version from AZURE API VERSION context + } } + + backend "local" {} } + +provider "azapi" {} ``` +Do NOT add `subscription_id` or `tenant_id` to the provider block. The az CLI context provides these. +Each stage uses the default `terraform.tfstate` in its own directory. +Cross-stage references use relative paths: `../stage-1-managed-identity/terraform.tfstate`. + +## CRITICAL: NO NULL VALUES IN BODY +azapi v2 serializes Terraform `null` as JSON `null`. ARM rejects properties +set to `null` — they must be ABSENT from the body, not null. -Only use a remote `backend "azurerm"` when the architecture explicitly calls for -shared remote state AND all required fields can be provided: +NEVER use ternary expressions that produce `null` for optional ARM properties: ```hcl -terraform { - backend "azurerm" { - resource_group_name = "terraform-state-rg" - storage_account_name = "tfstateXXXXX" # Must be a real account name - container_name = "tfstate" - key = "stageN-name.tfstate" +# WRONG — ARM returns 400 Bad Request +vnetConfiguration = var.enable_vnet ? { ... } : null +``` + +Instead, use `merge()` to conditionally include or omit the property: +```hcl +# CORRECT — property is absent when disabled +locals { + base = { appLogsConfiguration = { ... } } + vnet = var.enable_vnet ? { vnetConfiguration = { ... } } : {} +} +body = { properties = merge(local.base, local.vnet) } +``` + +## CRITICAL: TAGS PLACEMENT +Tags on `azapi_resource` MUST be a TOP-LEVEL attribute, NEVER inside `body`. + +CORRECT: +```hcl +resource "azapi_resource" "example" { + type = "Microsoft.Foo/bars@2024-01-01" + name = local.resource_name + parent_id = local.resource_group_id + location = var.location + tags = local.tags + body = { properties = { ... } } +} +``` + +WRONG (WILL BE REJECTED): +```hcl +resource "azapi_resource" "example" { + body = { tags = local.tags ... } # WRONG: inside body +} +``` + +## CRITICAL: locals.tf TEMPLATE +```hcl +locals { + zone_id = "zd" # Use zone from naming convention context + resource_suffix = "${var.environment}-${var.region_short}" + + tags = { + Environment = var.environment + Project = var.project_name + ManagedBy = "Terraform" + Stage = "stage-N-name" } } ``` -NEVER use variable references (var.*) in backend config — Terraform does not -support variables in backend blocks. Use literal values or omit the backend -entirely to use local state. +Tag keys MUST use PascalCase. `ManagedBy` value MUST be `"Terraform"` (capital T). + +## CRITICAL: PROVIDER RESTRICTIONS +The ONLY allowed provider is `hashicorp/azapi`. NEVER declare `azurerm` or `random`. +Use `var.subscription_id` and `var.tenant_id` instead of `data "azurerm_client_config"`. +Use `azapi_resource` for ALL resources including role assignments, metric alerts, and +diagnostic settings. Any `azurerm_*` resource WILL BE REJECTED. + +## CRITICAL: response_export_values (REQUIRED on EVERY azapi_resource) +Add `response_export_values = ["*"]` to EVERY `azapi_resource` block. This is +NOT optional — it is REQUIRED for the azapi provider to return any output data. +Without it, `.output` is empty and ALL downstream references fail silently. + +RULE: If you write `resource "azapi_resource"`, it MUST have `response_export_values = ["*"]`. +No exceptions. No "only when outputs reference it". ALWAYS include it. + +```hcl +resource "azapi_resource" "ANY_RESOURCE" { + type = "Microsoft.Xxx/yyy@version" + name = var.name + parent_id = var.parent_id + location = var.location + + response_export_values = ["*"] # <-- MANDATORY ON EVERY azapi_resource + + body = { ... } +} +``` + +VIOLATIONS THAT WILL BE REJECTED: +```hcl +resource "azapi_resource" "identity" { ... } # REJECTED — no response_export_values +resource "azapi_resource" "kv" { + type = "..." + body = { ... } + # REJECTED — missing response_export_values = ["*"] +} +``` + +""" + + SHARED_IAC_RULES + + """ + +## CRITICAL: deploy.sh CORRECTNESS +- `terraform output` does **NOT** have a `-state=` flag. To read outputs from a + specific state file, use `terraform output -json` from within the stage directory, + or parse the state file directly with `jq`. +- The cleanup trap **MUST** use the captured `$?` value, **NOT** a script-level + variable. Pattern: `cleanup() { local code=$?; ...; exit ${code}; }` + +## CRITICAL: CROSS-STAGE DEPENDENCIES +MANDATORY: Use `data "terraform_remote_state"` for ALL upstream references. +Do NOT define input variables for values that come from prior stages. +Accept ONLY the state FILE PATH as a variable. + +CRITICAL: Only reference stages explicitly listed as upstream dependencies +in the architecture context. Do NOT proactively add references to networking +or other stages unless they are listed as dependencies for THIS stage. + +When you have a resource ID from `terraform_remote_state`, use it directly as +`parent_id`. Do NOT create a `data "azapi_resource"` lookup just to validate it. + +WRONG (WILL BE REJECTED): +```hcl +variable "resource_group_id" { type = string } # Don't accept upstream values as variables +data "azapi_resource" "rg" { resource_id = ... } # Unnecessary API call +``` + +CORRECT: +```hcl +variable "stage1_state_path" { + description = "Path to Stage 1 state file" + type = string + default = "../stage-1-managed-identity/terraform.tfstate" +} +data "terraform_remote_state" "stage1" { + backend = "local" + config = { path = var.stage1_state_path } +} +# Use directly: +parent_id = data.terraform_remote_state.stage1.outputs.resource_group_id +``` + +NEVER use variable references in backend config blocks. ## MANAGED IDENTITY + RBAC (MANDATORY) When ANY service disables local/key-based authentication, you MUST ALSO: -1. Create a user-assigned managed identity as `azapi_resource` +1. Create a managed identity as `azapi_resource` 2. Create RBAC role assignments granting the identity access to that service -3. Output the identity's client_id and principal_id for application configuration -Failure to do this means the application CANNOT authenticate — the build is broken. - -## OUTPUTS (MANDATORY) -outputs.tf MUST export: -- Resource group name(s) -- All resource IDs that downstream stages reference -- All endpoints (URLs, FQDNs) downstream stages or applications need -- Managed identity client_id and principal_id -- Log Analytics workspace name and ID (if created) -- Key Vault name and URI (if created) -Do NOT output sensitive values (primary keys, connection strings). If a service -disables key-based auth, do NOT output keys with "don't use" warnings — simply -omit them. - -## deploy.sh (MANDATORY COMPLETENESS) -deploy.sh MUST be a complete, runnable script. NEVER truncate it. -It must include: -- #!/bin/bash and set -euo pipefail -- Azure login check (az account show) -- terraform init, plan -out=tfplan, apply tfplan -- terraform output -json > stage-N-outputs.json -- Cleanup of plan file (rm tfplan) -- trap for error handling and cleanup -- Complete echo statements (never leave a string unclosed) -- Post-deployment verification commands - -CRITICAL: -- NEVER use access keys, connection strings, or passwords -- ALWAYS use managed identity + RBAC role assignments via azapi_resource -- Include lifecycle blocks where appropriate -- Use depends_on sparingly (prefer implicit dependencies) -- NEVER output sensitive credentials — if local auth is disabled, omit keys entirely -- NEVER truncate deploy.sh — it must be complete and syntactically valid - -When generating files, wrap each file in a code block labeled with its path: -```terraform/main.tf - -``` - -When you need current Azure documentation or are uncertain about a service API, -SDK version, or configuration option, emit [SEARCH: your query] in your response. -The framework will fetch relevant Microsoft Learn documentation and re-invoke you -with the results. Use at most 2 search markers per response. Only search when your -built-in knowledge is insufficient. +3. Output the identity's client_id and principal_id + +## RBAC ROLE ASSIGNMENTS +```hcl +resource "azapi_resource" "acr_pull_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("6ba7b811-9dad-11d1-80b4-00c04fd430c8", + "${azapi_resource.registry.id}-${local.worker_principal_id}-7f951dda...") + parent_id = azapi_resource.registry.id + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/ + Microsoft.Authorization/roleDefinitions/7f951dda..." + principalId = local.worker_principal_id + principalType = "ServicePrincipal" + } + } +} +``` +ALWAYS use `uuidv5()` with the URL namespace UUID `6ba7b811-9dad-11d1-80b4-00c04fd430c8`. +ALWAYS include `principalType = "ServicePrincipal"` for managed identities. +NEVER use `uuid()` (non-deterministic) or `jsondecode()` on azapi v2.x output. +Access principal IDs via: `azapi_resource.identity.output.properties.principalId` + +## OUTPUT NAMING CONVENTION +Use these EXACT output key names for common values: +- Managed identity: `principal_id`, `client_id`, `identity_id`, `tenant_id` +- Resource group: `resource_group_id`, `resource_group_name` +- Log Analytics: `workspace_id`, `workspace_name`, `workspace_customer_id` +- Key Vault: `key_vault_id`, `key_vault_name`, `vault_uri` +- Networking: `vnet_id`, `pe_subnet_id`, `private_dns_zone_ids` + +Do NOT prefix with stage names (use `principal_id` not `worker_identity_principal_id`). +Every output MUST have a `description` field. + +## STANDARD VARIABLES +Every stage MUST define these in variables.tf with validation where applicable: +```hcl +variable "subscription_id" { type = string; description = "Azure subscription ID" } +variable "tenant_id" { type = string; description = "Azure tenant ID" } +variable "project_name" { type = string; description = "Project identifier" } +variable "environment" { + type = string + default = "dev" + validation { + condition = contains(["dev", "staging", "prod"], var.environment) + error_message = "environment must be one of: dev, staging, prod." + } +} +variable "location" { type = string; description = "Azure region" } +variable "region_short" { type = string; default = "wus3"; description = "Short region code" } +``` +Every variable MUST have a `description` field. + +## DIAGNOSTIC SETTINGS +Every data service MUST have a diagnostic settings resource: +```hcl +resource "azapi_resource" "diag" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${local.resource_name}" + parent_id = azapi_resource.primary_resource.id + body = { + properties = { + workspaceId = data.terraform_remote_state.stage2.outputs.workspace_id + logCategoryGroups = [{ category_group = "allLogs", enabled = true }] + metrics = [{ category = "AllMetrics", enabled = true }] + } + } +} +``` +Use `allLogs` category group (NOT individual log categories). Include `AllMetrics`. + +## CRITICAL: deploy.sh REQUIREMENTS — SCRIPTS UNDER 150 LINES WILL BE REJECTED +deploy.sh MUST include ALL of the following: + +1. `#!/usr/bin/env bash` and `set -euo pipefail` (EXACTLY this shebang) +2. Color-coded logging functions (use these EXACT names): + ```bash + RED='\\033[0;31m'; GREEN='\\033[0;32m'; YELLOW='\\033[1;33m'; BLUE='\\033[0;34m'; NC='\\033[0m' + info() { echo -e "${BLUE}[INFO]${NC} $*"; } + success() { echo -e "${GREEN}[OK]${NC} $*"; } + warn() { echo -e "${YELLOW}[WARN]${NC} $*"; } + error() { echo -e "${RED}[ERROR]${NC} $*" >&2; } + ``` +3. Argument parsing: `--dry-run`, `--destroy`, `--auto-approve`, `-h|--help` +4. Pre-flight: `az account show`, tool checks, upstream state file validation +5. `terraform init -input=false` then `terraform validate` +6. `terraform plan -out=tfplan -detailed-exitcode` +7. `terraform apply tfplan` +8. `terraform output -json > outputs.json` +9. Post-deployment verification via `az` CLI +10. `trap cleanup EXIT` with `exit ${exit_code}` +11. Destroy mode with `terraform plan -destroy` + +deploy.sh VARIABLE CONVENTION: +Use `TF_VAR_` prefixed environment variables for all Terraform inputs. +Do NOT use `ARM_SUBSCRIPTION_ID` or `AZURE_SUBSCRIPTION_ID`. + +deploy.sh AUTO-APPROVE PATTERN: +```bash +[[ "${AUTO_APPROVE}" == "true" ]] && APPROVE_FLAG="-auto-approve" || APPROVE_FLAG="" +``` +NOTE: Terraform uses SINGLE dash `-auto-approve` (NOT `--auto-approve`). +Do NOT use `${VAR:+flag}` expansion for boolean flags. + +deploy.sh CONTROL FLOW: +```bash +if [[ "${DESTROY}" == "true" ]]; then + terraform plan -destroy -out="${PLAN_FILE}" ... + [[ "${DRY_RUN}" == "true" ]] && { info "Dry run complete."; exit 0; } + terraform apply ${APPROVE_FLAG} "${PLAN_FILE}" +else + terraform plan -out="${PLAN_FILE}" -detailed-exitcode ... || PLAN_EXIT=$? + [[ "${DRY_RUN}" == "true" ]] && { info "Dry run complete."; exit 0; } + terraform apply ${APPROVE_FLAG} "${PLAN_FILE}" +fi +``` + +## SENSITIVE VALUES +NEVER pass sensitive values (keys, connection strings) as plaintext container app +environment variables. Use Key Vault references instead. +NEVER output primary keys or connection strings in outputs.tf. + +## CODE QUALITY +- Use `depends_on` sparingly (prefer implicit dependencies via resource references) +- Use `lifecycle { ignore_changes }` ONLY for properties Azure mutates independently +- Every `azapi_resource` whose `.output.properties` is referenced MUST have `response_export_values = ["*"]` + +## DESIGN NOTES (REQUIRED at end of response) +After all code blocks, include a `## Key Design Decisions` section: +1. List each significant decision as a numbered item +2. Explain WHY (policy reference, architecture constraint) +3. Note deviations from architecture context and why (e.g., policy override) +4. Reference policy IDs where applicable (e.g., "per AZ-VNET-001") + +## OUTPUT FORMAT +Use SHORT filenames in code block labels (e.g., `main.tf`, NOT `terraform/main.tf` +or `concept/infra/terraform/stage-1/main.tf`). + +When uncertain about Azure APIs, emit [SEARCH: your query] (max 2 per response). """ +) diff --git a/azext_prototype/agents/governance.py b/azext_prototype/agents/governance.py index 064aac6..b3e8ee5 100644 --- a/azext_prototype/agents/governance.py +++ b/azext_prototype/agents/governance.py @@ -23,6 +23,7 @@ from azext_prototype.governance import anti_patterns from azext_prototype.governance.policies import PolicyEngine +from azext_prototype.governance.transforms import reset_cache as _reset_transforms from azext_prototype.templates.registry import TemplateRegistry logger = logging.getLogger(__name__) @@ -56,6 +57,7 @@ def reset_caches() -> None: _policy_engine = None _template_registry = None anti_patterns.reset_cache() + _reset_transforms() class GovernanceContext: @@ -131,6 +133,8 @@ def check_response_for_violations( self, agent_name: str, response_text: str, + iac_tool: str | None = None, + services: list[str] | None = None, ) -> list[str]: """Scan AI output for anti-pattern matches. @@ -140,4 +144,4 @@ def check_response_for_violations( Returns a list of human-readable warning strings (empty = clean). """ - return anti_patterns.scan(response_text) + return anti_patterns.scan(response_text, iac_tool=iac_tool, agent_name=agent_name, services=services) diff --git a/azext_prototype/ai/azure_openai.py b/azext_prototype/ai/azure_openai.py index 8c25a02..d89feb3 100644 --- a/azext_prototype/ai/azure_openai.py +++ b/azext_prototype/ai/azure_openai.py @@ -14,7 +14,13 @@ from knack.util import CLIError -from azext_prototype.ai.provider import AIMessage, AIProvider, AIResponse, ToolCall +from azext_prototype.ai.provider import ( + AIMessage, + AIProvider, + AIResponse, + extract_tool_calls_from_openai, + messages_to_dicts, +) logger = logging.getLogger(__name__) @@ -135,40 +141,6 @@ def _create_client(self): "Ensure you are logged in via 'az login' or have managed identity configured." ) - @staticmethod - def _messages_to_dicts(messages: list[AIMessage]) -> list[dict[str, Any]]: - """Convert AIMessage list to OpenAI-style message dicts.""" - result = [] - for m in messages: - msg: dict[str, Any] = {"role": m.role, "content": m.content} - if m.tool_calls: - msg["tool_calls"] = [ - { - "id": tc.id, - "type": "function", - "function": {"name": tc.name, "arguments": tc.arguments}, - } - for tc in m.tool_calls - ] - if m.tool_call_id: - msg["tool_call_id"] = m.tool_call_id - result.append(msg) - return result - - @staticmethod - def _extract_tool_calls(choice: Any) -> list[ToolCall] | None: - """Extract tool calls from an OpenAI SDK response choice.""" - if not hasattr(choice.message, "tool_calls") or not choice.message.tool_calls: - return None - return [ - ToolCall( - id=tc.id, - name=tc.function.name, - arguments=tc.function.arguments or "{}", - ) - for tc in choice.message.tool_calls - ] - def chat( self, messages: list[AIMessage], @@ -180,7 +152,7 @@ def chat( ) -> AIResponse: """Send a chat completion via Azure OpenAI.""" deployment = model or self._deployment - api_messages = self._messages_to_dicts(messages) + api_messages = messages_to_dicts(messages) kwargs: dict[str, Any] = { "model": deployment, @@ -215,7 +187,7 @@ def chat( model=response.model, usage=usage, finish_reason=choice.finish_reason or "stop", - tool_calls=self._extract_tool_calls(choice), + tool_calls=extract_tool_calls_from_openai(choice), ) def stream_chat( diff --git a/azext_prototype/ai/copilot_provider.py b/azext_prototype/ai/copilot_provider.py index 7b68742..456398e 100644 --- a/azext_prototype/ai/copilot_provider.py +++ b/azext_prototype/ai/copilot_provider.py @@ -28,7 +28,53 @@ from azext_prototype.ai.copilot_auth import ( get_copilot_token, ) -from azext_prototype.ai.provider import AIMessage, AIProvider, AIResponse, ToolCall +from azext_prototype.ai.provider import ( + AIMessage, + AIProvider, + AIResponse, + ToolCall, + messages_to_dicts, +) + + +class CopilotTimeoutError(CLIError): + """Raised when the Copilot API request times out. + + Extends ``CLIError`` so it propagates cleanly through the Azure CLI + error handling, but can be caught specifically by retry logic in the + build session. + """ + + +class CopilotPromptTooLargeError(CLIError): + """Raised when the prompt exceeds the Copilot API's token limit. + + The Copilot API enforces a model-level prompt token cap (typically + 168,000 tokens) that is lower than the model's native context window. + Callers can catch this and truncate/chunk the prompt before retrying. + + Attributes: + token_count: Number of tokens the prompt contained. + token_limit: Maximum tokens the API accepts. + """ + + def __init__(self, message: str, token_count: int = 0, token_limit: int = 0): + super().__init__(message) + self.token_count = token_count + self.token_limit = token_limit + + +class CopilotRateLimitError(CLIError): + """Raised when the Copilot API returns HTTP 429 (rate limited). + + Attributes: + retry_after: Seconds to wait before retrying (from Retry-After header). + """ + + def __init__(self, message: str, retry_after: int = 0): + super().__init__(message) + self.retry_after = retry_after + logger = logging.getLogger(__name__) @@ -44,8 +90,10 @@ _MODELS_URL = f"{_BASE_URL}/models" # Default request timeout in seconds. Architecture generation and -# large prompts can take several minutes; 5 minutes is a safe default. -_DEFAULT_TIMEOUT = 300 +# large prompts can take several minutes; 10 minutes is a safe default. +# The discovery system prompt alone is ~69KB (governance + templates + +# architect context), and QA remediation prompts can reach 235KB+. +_DEFAULT_TIMEOUT = 600 class CopilotProvider(AIProvider): @@ -95,26 +143,6 @@ def _headers(self) -> dict[str, str]: "X-Request-Id": str(uuid.uuid4()), } - @staticmethod - def _messages_to_dicts(messages: list[AIMessage]) -> list[dict[str, Any]]: - """Convert ``AIMessage`` list to OpenAI-style message dicts.""" - result = [] - for m in messages: - msg: dict[str, Any] = {"role": m.role, "content": m.content} - if m.tool_calls: - msg["tool_calls"] = [ - { - "id": tc.id, - "type": "function", - "function": {"name": tc.name, "arguments": tc.arguments}, - } - for tc in m.tool_calls - ] - if m.tool_call_id: - msg["tool_call_id"] = m.tool_call_id - result.append(msg) - return result - # ------------------------------------------------------------------ # AIProvider interface # ------------------------------------------------------------------ @@ -132,7 +160,7 @@ def chat( target_model = model or self._model payload: dict[str, Any] = { "model": target_model, - "messages": self._messages_to_dicts(messages), + "messages": messages_to_dicts(messages, filter_empty=True), "temperature": temperature, "max_tokens": max_tokens, } @@ -155,6 +183,21 @@ def chat( prompt_chars, ) + from azext_prototype.debug_log import debug as _dbg + + _dbg( + "CopilotProvider.chat", + "Sending request", + model=target_model, + messages=len(messages), + prompt_chars=prompt_chars, + max_tokens=max_tokens, + timeout=self._timeout, + ) + + import time as _time + + _t0 = _time.perf_counter() try: resp = requests.post( _COMPLETIONS_URL, @@ -163,14 +206,23 @@ def chat( timeout=self._timeout, ) except requests.Timeout: - raise CLIError( - f"Copilot API timed out after {self._timeout}s.\n" - "For very large prompts, increase the timeout:\n" - " set COPILOT_TIMEOUT=600" - ) + elapsed = _time.perf_counter() - _t0 + _dbg("CopilotProvider.chat", "TIMEOUT", elapsed_s=f"{elapsed:.1f}", timeout=self._timeout) + raise CopilotTimeoutError(f"Copilot API timed out after {self._timeout}s.") except requests.RequestException as exc: raise CLIError(f"Failed to reach Copilot API: {exc}") from exc + _elapsed = _time.perf_counter() - _t0 + request_id = resp.headers.get("x-request-id", "") or resp.headers.get("x-github-request-id", "") + _dbg( + "CopilotProvider.chat", + "Response received", + elapsed_s=f"{_elapsed:.1f}", + status=resp.status_code, + response_chars=len(resp.text), + request_id=request_id, + ) + # 401 → token may be invalid or revoked; retry once if resp.status_code == 401: logger.debug("Got 401 — retrying request") @@ -183,6 +235,26 @@ def chat( ) except requests.RequestException as exc: raise CLIError(f"Copilot API retry failed: {exc}") from exc + request_id = resp.headers.get("x-request-id", "") + + # 429 → rate limited; extract Retry-After header + if resp.status_code == 429: + retry_after = 0 + ra_header = resp.headers.get("Retry-After", resp.headers.get("retry-after", "")) + try: + retry_after = int(ra_header) + except (ValueError, TypeError): + retry_after = 60 # Default if header missing or unparseable + _dbg( + "CopilotProvider.chat", + "RATE_LIMITED", + retry_after=retry_after, + request_id=request_id, + ) + raise CopilotRateLimitError( + f"Copilot API rate limited (HTTP 429). Retry after {retry_after}s.", + retry_after=retry_after, + ) if resp.status_code != 200: body = "" @@ -190,10 +262,34 @@ def chat( body = resp.text[:500] except Exception: pass - raise CLIError( - f"Copilot API error (HTTP {resp.status_code}):\n{body}\n\n" - "Ensure you have a valid GitHub Copilot Business or Enterprise license." - ) + + # Parse structured error for specific handling + error_code = "" + try: + err_data = resp.json() + error_obj = err_data.get("error", {}) + error_code = error_obj.get("code", "") + except Exception: + pass + + if error_code == "model_max_prompt_tokens_exceeded": + # Extract token counts from the error message + import re as _re + + token_count = 0 + token_limit = 0 + match = _re.search(r"(\d+)\s+exceeds the limit of\s+(\d+)", body) + if match: + token_count = int(match.group(1)) + token_limit = int(match.group(2)) + raise CopilotPromptTooLargeError( + f"Prompt too large: {token_count:,} tokens exceeds " + f"the Copilot API limit of {token_limit:,} tokens.", + token_count=token_count, + token_limit=token_limit, + ) + + raise CLIError(f"Copilot API error (HTTP {resp.status_code}):\n{body}") try: data = resp.json() @@ -223,12 +319,32 @@ def chat( usage = data.get("usage", {}) + # Capture PRU (Premium Request Units) — may be in usage body or response headers + pru = usage.get("premium_request_units") or usage.get("pru") or usage.get("copilot_premium_request_units") + if pru is None: + pru_header = resp.headers.get("x-github-copilot-pru") or resp.headers.get("x-copilot-pru") + if pru_header: + try: + pru = int(pru_header) + except (ValueError, TypeError): + pass + + # Log response headers in debug mode for PRU field discovery + _dbg( + "CopilotProvider.chat", + "Response usage and headers", + usage_keys=list(usage.keys()), + finish_reason=finish, + pru=pru, + ) + return AIResponse( content=content, model=target_model, usage={ "prompt_tokens": usage.get("prompt_tokens", 0), "completion_tokens": usage.get("completion_tokens", 0), + "_copilot": True, # Signals TokenTracker to compute PRUs }, finish_reason=finish, tool_calls=tool_calls_data, @@ -245,7 +361,7 @@ def stream_chat( target_model = model or self._model payload: dict[str, Any] = { "model": target_model, - "messages": self._messages_to_dicts(messages), + "messages": messages_to_dicts(messages, filter_empty=True), "temperature": temperature, "max_tokens": max_tokens, "stream": True, @@ -264,7 +380,7 @@ def stream_chat( ) resp.raise_for_status() except requests.Timeout: - raise CLIError(f"Copilot streaming timed out after {self._timeout}s.") + raise CopilotTimeoutError(f"Copilot streaming timed out after {self._timeout}s.") except requests.RequestException as exc: raise CLIError(f"Copilot streaming request failed: {exc}") from exc @@ -317,6 +433,7 @@ def list_models(self) -> list[dict]: return [ {"id": "claude-sonnet-4", "name": "Claude Sonnet 4"}, {"id": "claude-sonnet-4.5", "name": "Claude Sonnet 4.5"}, + {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"}, {"id": "gpt-4.1", "name": "GPT-4.1"}, {"id": "gpt-5-mini", "name": "GPT-5 Mini"}, {"id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro"}, diff --git a/azext_prototype/ai/github_models.py b/azext_prototype/ai/github_models.py index 22e807f..93c5ccf 100644 --- a/azext_prototype/ai/github_models.py +++ b/azext_prototype/ai/github_models.py @@ -6,7 +6,13 @@ from knack.util import CLIError -from azext_prototype.ai.provider import AIMessage, AIProvider, AIResponse, ToolCall +from azext_prototype.ai.provider import ( + AIMessage, + AIProvider, + AIResponse, + extract_tool_calls_from_openai, + messages_to_dicts, +) logger = logging.getLogger(__name__) @@ -43,40 +49,6 @@ def _create_client(self): api_key=self._token, ) - @staticmethod - def _messages_to_dicts(messages: list[AIMessage]) -> list[dict[str, Any]]: - """Convert AIMessage list to OpenAI-style message dicts.""" - result = [] - for m in messages: - msg: dict[str, Any] = {"role": m.role, "content": m.content} - if m.tool_calls: - msg["tool_calls"] = [ - { - "id": tc.id, - "type": "function", - "function": {"name": tc.name, "arguments": tc.arguments}, - } - for tc in m.tool_calls - ] - if m.tool_call_id: - msg["tool_call_id"] = m.tool_call_id - result.append(msg) - return result - - @staticmethod - def _extract_tool_calls(choice: Any) -> list[ToolCall] | None: - """Extract tool calls from an OpenAI SDK response choice.""" - if not hasattr(choice.message, "tool_calls") or not choice.message.tool_calls: - return None - return [ - ToolCall( - id=tc.id, - name=tc.function.name, - arguments=tc.function.arguments or "{}", - ) - for tc in choice.message.tool_calls - ] - def chat( self, messages: list[AIMessage], @@ -89,7 +61,7 @@ def chat( """Send a chat completion via GitHub Models API.""" target_model = model or self._model - api_messages = self._messages_to_dicts(messages) + api_messages = messages_to_dicts(messages) kwargs: dict[str, Any] = { "model": target_model, @@ -127,7 +99,7 @@ def chat( model=response.model, usage=usage, finish_reason=choice.finish_reason or "stop", - tool_calls=self._extract_tool_calls(choice), + tool_calls=extract_tool_calls_from_openai(choice), ) def stream_chat( diff --git a/azext_prototype/ai/provider.py b/azext_prototype/ai/provider.py index da86853..e2ac4a0 100644 --- a/azext_prototype/ai/provider.py +++ b/azext_prototype/ai/provider.py @@ -108,3 +108,60 @@ def provider_name(self) -> str: @abstractmethod def default_model(self) -> str: """Return the default model ID for this provider.""" + + +# ------------------------------------------------------------------ # +# Shared utilities for AI providers +# ------------------------------------------------------------------ # + + +def messages_to_dicts( + messages: list[AIMessage], + filter_empty: bool = False, +) -> list[dict[str, Any]]: + """Convert AIMessage list to OpenAI-style message dicts. + + Parameters + ---------- + messages: + Conversation messages to serialize. + filter_empty: + If True, skip messages with empty/whitespace-only content + (prevents HTTP 400 from APIs that reject empty text blocks). + """ + result = [] + for m in messages: + if filter_empty and isinstance(m.content, str) and (not m.content or not m.content.strip()): + continue + msg: dict[str, Any] = {"role": m.role, "content": m.content} + if m.tool_calls: + msg["tool_calls"] = [ + { + "id": tc.id, + "type": "function", + "function": {"name": tc.name, "arguments": tc.arguments}, + } + for tc in m.tool_calls + ] + if m.tool_call_id: + msg["tool_call_id"] = m.tool_call_id + result.append(msg) + return result + + +def extract_tool_calls_from_openai(choice: Any) -> list[ToolCall] | None: + """Extract tool calls from an OpenAI SDK response choice. + + Works with both ``openai`` SDK and ``azure-ai-inference`` SDK + response objects that follow the OpenAI schema. + """ + if not hasattr(choice.message, "tool_calls") or not choice.message.tool_calls: + return None + return [ + ToolCall( + id=tc.id, + name=tc.function.name, + arguments=tc.function.arguments or "{}", + ) + for tc in choice.message.tool_calls + ] diff --git a/azext_prototype/ai/token_tracker.py b/azext_prototype/ai/token_tracker.py index b9f7caf..ef7c50b 100644 --- a/azext_prototype/ai/token_tracker.py +++ b/azext_prototype/ai/token_tracker.py @@ -7,6 +7,7 @@ from __future__ import annotations from dataclasses import dataclass, field +from typing import Any # Model context-window sizes (prompt token budget). # Used for budget-percentage display. Values are the *input* context @@ -28,11 +29,45 @@ # Claude models (Copilot) "claude-sonnet-4": 200_000, "claude-sonnet-4.5": 200_000, + "claude-sonnet-4.6": 200_000, "claude-haiku-4.5": 200_000, "claude-opus-4": 200_000, + "claude-opus-4.5": 200_000, + "claude-opus-4.6": 200_000, # Gemini models (Copilot) "gemini-2.0-flash": 1_048_576, "gemini-2.5-pro": 1_048_576, + "gemini-3-flash": 1_048_576, + "gemini-3-pro": 1_048_576, +} + +# GitHub Copilot Premium Request Unit (PRU) multipliers. +# Each API call costs (1 × multiplier) PRUs. Only applies to the +# Copilot provider — models not in this table produce 0 PRUs. +# Source: https://docs.github.com/en/copilot/concepts/billing/copilot-requests +_PRU_MULTIPLIERS: dict[str, float] = { + # Included with paid plans (0 PRUs) + "gpt-5-mini": 0, + "gpt-4.1": 0, + "gpt-4o": 0, + # Low-cost (0.25–0.33 PRUs per request) + "grok-code-fast-1": 0.25, + "claude-haiku-4.5": 0.33, + "gemini-3-flash": 0.33, + "gpt-5.1-codex-mini": 0.33, + "gpt-5.4-mini": 0.33, + # Standard (1 PRU per request) + "claude-sonnet-4": 1, + "claude-sonnet-4.5": 1, + "claude-sonnet-4.6": 1, + "gemini-3-pro": 1, + "gemini-3-pro-1.5": 1, + "gpt-5.1": 1, + "gpt-5.2": 1, + "gpt-5.4": 1, + # Premium (3+ PRUs per request) + "claude-opus-4.5": 3, + "claude-opus-4.6": 3, } @@ -57,8 +92,12 @@ class TokenTracker: _this_turn_completion: int = field(default=0, repr=False) _session_prompt: int = field(default=0, repr=False) _session_completion: int = field(default=0, repr=False) + _this_turn_pru: float = field(default=0.0, repr=False) + _session_pru: float = field(default=0.0, repr=False) _turn_count: int = field(default=0, repr=False) _model: str = field(default="", repr=False) + _is_copilot: bool = field(default=False, repr=False) + _on_update: Any = field(default=None, repr=False) # ------------------------------------------------------------------ # Public API @@ -81,6 +120,23 @@ def record(self, response) -> None: if model: self._model = model + # Auto-detect Copilot provider from usage metadata + if usage.get("_copilot"): + self._is_copilot = True + + # Compute PRUs from the model multiplier table (Copilot only). + # Each API call = 1 request × multiplier. + pru = self._compute_pru(model) + self._this_turn_pru = pru + self._session_pru += pru + + # Auto-push status update to the UI if a callback is set + if self._on_update: + try: + self._on_update(self.format_status()) + except Exception: + pass # Never let UI callbacks break the AI flow + @property def this_turn(self) -> int: """Tokens used in the most recent turn (prompt + completion).""" @@ -106,6 +162,11 @@ def model(self) -> str: """Most recently seen model name.""" return self._model + @property + def session_pru(self) -> float: + """Cumulative Premium Request Units (Copilot only).""" + return self._session_pru + @property def budget_pct(self) -> float | None: """Percentage of context window consumed (prompt tokens only). @@ -131,6 +192,12 @@ def format_status(self) -> str: f"{self.this_turn:,} tokens this turn", f"{self.session_total:,} session", ] + if self._session_pru > 0: + # Display as integer when whole, otherwise 1 decimal place + if self._session_pru == int(self._session_pru): + parts.append(f"{int(self._session_pru):,} PRUs") + else: + parts.append(f"{self._session_pru:.1f} PRUs") pct = self.budget_pct if pct is not None: parts.append(f"~{pct:.0f}%") @@ -138,7 +205,7 @@ def format_status(self) -> str: def to_dict(self) -> dict: """Serialisable snapshot (for state persistence or telemetry).""" - return { + d: dict = { "this_turn": { "prompt": self._this_turn_prompt, "completion": self._this_turn_completion, @@ -150,25 +217,44 @@ def to_dict(self) -> dict: "turn_count": self._turn_count, "model": self._model, } + if self._session_pru > 0: + d["session"]["premium_request_units"] = self._session_pru + return d # ------------------------------------------------------------------ # Internal # ------------------------------------------------------------------ - def _get_context_window(self) -> int | None: - """Look up the context window for the current model.""" - if not self._model: - return None + @staticmethod + def _lookup_model(model_name: str, table: dict) -> object | None: + """Look up *model_name* in *table* using exact-then-substring matching. - model_lower = self._model.lower() + Returns the matched value or ``None`` if no match is found. + """ + model_lower = model_name.lower() + if model_lower in table: + return table[model_lower] + for key, value in table.items(): + if key in model_lower: + return value + return None - # Exact match first - if model_lower in _CONTEXT_WINDOWS: - return _CONTEXT_WINDOWS[model_lower] + def _compute_pru(self, model: str) -> float: + """Compute PRUs for one API request based on the model multiplier. - # Substring match (e.g. "gpt-4o-2024-05-13" matches "gpt-4o") - for key, window in _CONTEXT_WINDOWS.items(): - if key in model_lower: - return window + Returns 0 for non-Copilot sessions or unknown models. + """ + if not self._is_copilot or not model: + return 0.0 + result = self._lookup_model(model, _PRU_MULTIPLIERS) + if result is not None: + return result # type: ignore[return-value] + # Unknown model on Copilot — assume 1 PRU (standard rate) + return 1.0 - return None + def _get_context_window(self) -> int | None: + """Look up the context window for the current model.""" + if not self._model: + return None + result = self._lookup_model(self._model, _CONTEXT_WINDOWS) + return result # type: ignore[return-value] diff --git a/azext_prototype/azext_metadata.json b/azext_prototype/azext_metadata.json index ace5c86..33cd7d7 100644 --- a/azext_prototype/azext_metadata.json +++ b/azext_prototype/azext_metadata.json @@ -2,7 +2,7 @@ "azext.isPreview": true, "azext.minCliCoreVersion": "2.50.0", "name": "prototype", - "version": "0.2.1b5", + "version": "0.2.1b6", "azext.summary": "Azure CLI extension for building rapid prototypes with GitHub Copilot.", "license": "MIT", "classifiers": [ diff --git a/azext_prototype/commands.py b/azext_prototype/commands.py index cb6ff60..824a797 100644 --- a/azext_prototype/commands.py +++ b/azext_prototype/commands.py @@ -11,6 +11,7 @@ def load_command_table(self, _): g.custom_command("build", "prototype_build") g.custom_command("deploy", "prototype_deploy") g.custom_command("status", "prototype_status") + g.custom_command("validate", "prototype_validate") with self.command_group("prototype analyze", is_preview=True) as g: g.custom_command("error", "prototype_analyze_error") diff --git a/azext_prototype/custom.py b/azext_prototype/custom.py index 41e75ec..7dc50b7 100644 --- a/azext_prototype/custom.py +++ b/azext_prototype/custom.py @@ -9,7 +9,6 @@ import json import logging import os -import signal from datetime import datetime, timezone from pathlib import Path @@ -29,7 +28,7 @@ def _quiet_output(fn): """Suppress Azure CLI's automatic JSON serialization of return values. Most commands print formatted output via the console module. The dict - they return is then *also* serialised by Azure CLI as JSON, which is + they return is then *also* serialized by Azure CLI as JSON, which is extremely noisy for interactive workflows. This decorator swallows the return value (returning ``None`` so Azure @@ -232,6 +231,12 @@ def _prepare_command(project_dir: str | None = None): (project_dir, config, registry, agent_context) """ project_dir = project_dir or _get_project_dir() + + # Initialize debug logging if DEBUG_PROTOTYPE=true + from azext_prototype.debug_log import init_debug_log, log_session_start + + init_debug_log(project_dir) + config = _load_config(project_dir) # Validate external tool versions before proceeding @@ -241,6 +246,15 @@ def _prepare_command(project_dir: str | None = None): registry = _build_registry(config, project_dir) mcp_manager = _build_mcp_manager(config, project_dir) agent_context = _build_context(config, project_dir, mcp_manager=mcp_manager) + + # Log session context for debug + log_session_start( + project_dir=project_dir, + ai_provider=config.get("ai.provider", ""), + model=config.get("ai.model", ""), + iac_tool=iac_tool or "", + ) + return project_dir, config, registry, agent_context @@ -391,22 +405,11 @@ def prototype_init( def _run_tui(app) -> None: - """Run a Textual app with clean Ctrl+C handling. - - Suppresses SIGINT during the Textual run so that Ctrl+C is handled - exclusively as a key event by the Textual binding (``ctrl+c`` → - ``action_quit``). This prevents ``KeyboardInterrupt`` from - propagating to the Azure CLI framework and, on Windows, eliminates - the "Terminate batch job (Y/N)?" prompt from ``az.cmd``. - """ - prev = signal.getsignal(signal.SIGINT) + """Run a Textual app, suppressing KeyboardInterrupt on exit.""" try: - signal.signal(signal.SIGINT, lambda *_: None) app.run() - except KeyboardInterrupt: - pass # clean exit - finally: - signal.signal(signal.SIGINT, prev) + except (KeyboardInterrupt, SystemExit): + pass @_quiet_output @@ -553,6 +556,24 @@ def prototype_build(cmd, scope="all", dry_run=False, status=False, reset=False, stage = BuildStage() _check_guards(stage) + # Launch TUI for interactive builds (same pattern as design stage). + # Skip TUI for dry-run, --json, or non-interactive (e.g. tests). + import sys + + if not dry_run and not json_output and sys.stdout.isatty(): + from azext_prototype.ui.app import PrototypeApp + + stage_kwargs = {"scope": scope, "reset": reset, "auto_accept": auto_accept} + + app = PrototypeApp( + start_stage="build", + project_dir=project_dir, + stage_kwargs=stage_kwargs, + ) + _run_tui(app) + return {"status": "completed"} + + # Non-TUI path: dry-run, --json, or non-interactive try: result = stage.execute( agent_context, @@ -689,6 +710,32 @@ def prototype_deploy( deploy_stage = DeployStage() _check_guards(deploy_stage) + # Launch TUI for interactive deploys (same pattern as design/build). + # Skip TUI for dry-run, single-stage, --json, or non-interactive. + import sys + + if not dry_run and stage is None and not json_output and sys.stdout.isatty(): + from azext_prototype.ui.app import PrototypeApp + + stage_kwargs = { + "force": force, + "reset": reset, + "subscription": subscription, + "tenant": tenant, + } + if service_principal: + stage_kwargs["client_id"] = sp_client_id + stage_kwargs["client_secret"] = sp_secret + + app = PrototypeApp( + start_stage="deploy", + project_dir=project_dir, + stage_kwargs=stage_kwargs, + ) + _run_tui(app) + return {"status": "completed"} + + # Non-interactive: dry-run or single-stage deploy try: return deploy_stage.execute( agent_context, @@ -816,6 +863,75 @@ def _deploy_generate_scripts( return {"status": "generated", "scripts": generated, "deploy_type": deploy_type} +@track("prototype validate") +def prototype_validate( + cmd, + all_areas=False, + policies=False, + anti_patterns=False, + standards=False, + workloads=False, + strict=False, + json_output=False, +): + """Validate governance YAML files (policies, anti-patterns, standards, workloads).""" + from azext_prototype.governance.validate import ( + validate_anti_patterns, + validate_policies, + validate_standards, + validate_workloads, + ) + + # Default to --all if no specific flags + if not all_areas and not policies and not anti_patterns and not standards and not workloads: + all_areas = True + + errors = [] + areas = [] + + if all_areas or policies: + areas.append("policies") + errors.extend(validate_policies()) + + if all_areas or anti_patterns: + areas.append("anti-patterns") + errors.extend(validate_anti_patterns()) + + if all_areas or standards: + areas.append("standards") + errors.extend(validate_standards()) + + if all_areas or workloads: + areas.append("workloads") + errors.extend(validate_workloads()) + + actual_errors = [e for e in errors if e.severity == "error"] + warnings = [e for e in errors if e.severity == "warning"] + + if json_output: + return { + "areas": areas, + "errors": [{"file": e.file, "message": e.message, "severity": e.severity} for e in errors], + "error_count": len(actual_errors), + "warning_count": len(warnings), + "valid": len(actual_errors) == 0 and (not strict or len(warnings) == 0), + } + + print(f"Validating: {', '.join(areas)}") + + if not errors: + print("All governance files are valid.") + return + + for err in errors: + print(str(err)) + + print(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)") + + if actual_errors or (strict and warnings): + raise CLIError(f"Governance validation failed: {len(actual_errors)} error(s), {len(warnings)} warning(s)") + + @_quiet_output @track("prototype status") def prototype_status(cmd, detailed=False, json_output=False): @@ -2458,7 +2574,7 @@ def _load_speckit_context(project_dir: str) -> str: ) rows.append( f"| {st.get('stage', '?')} | {st.get('name', '?')} " - f"| {st.get('category', '?')} | {st.get('status', '?')} " + f"| {st.get('capability', '?')} | {st.get('status', '?')} " f"| {svcs} |" ) sections.append("## Build Stages\n" + "\n".join(rows)) diff --git a/azext_prototype/debug_log.py b/azext_prototype/debug_log.py new file mode 100644 index 0000000..7a2506d --- /dev/null +++ b/azext_prototype/debug_log.py @@ -0,0 +1,274 @@ +"""Exhaustive debug logging for prototype sessions. + +Activated by setting ``DEBUG_PROTOTYPE=true`` in the environment. +When active, writes to ``debug_YYYYMMDDHHMMSS.log`` in the project +directory. When the variable is absent or not ``"true"``, every +function is a no-op with near-zero overhead. + +The log is designed to be **diagnostic** — it captures full message +content, state mutations, decision branches, timing, and errors so +that developers, testers, or end-users can send it for examination +without needing to reproduce the issue. +""" + +from __future__ import annotations + +import logging +import os +import platform +import sys +import time +import traceback +from contextlib import contextmanager +from datetime import datetime +from pathlib import Path +from typing import Any, Iterator + +_debug_logger: logging.Logger | None = None +_log_path: Path | None = None + +# Maximum chars to include from a single content field in the log. +# Set high intentionally — the log should be exhaustive, not abbreviated. +_CONTENT_LIMIT = 2000 + + +# ------------------------------------------------------------------ # +# Initialization +# ------------------------------------------------------------------ # + + +def init_debug_log(project_dir: str) -> None: + """Initialize debug logging if ``DEBUG_PROTOTYPE=true``.""" + if os.environ.get("DEBUG_PROTOTYPE", "").lower() != "true": + return + global _debug_logger, _log_path + ts = datetime.now().strftime("%Y%m%d%H%M%S") + _log_path = Path(project_dir) / f"debug_{ts}.log" + _log_path.parent.mkdir(parents=True, exist_ok=True) + _debug_logger = logging.getLogger("prototype.debug") + _debug_logger.setLevel(logging.DEBUG) + # Avoid duplicate handlers on re-init + if not _debug_logger.handlers: + handler = logging.FileHandler(_log_path, encoding="utf-8") + handler.setFormatter(logging.Formatter("%(asctime)s | %(message)s", datefmt="%Y-%m-%d %H:%M:%S")) + _debug_logger.addHandler(handler) + _debug_logger.info("=== Prototype Debug Session ===") + + +def is_active() -> bool: + """Return True when debug logging is active.""" + return _debug_logger is not None + + +def get_log_path() -> Path | None: + """Return the path of the current debug log file, or None.""" + return _log_path + + +# ------------------------------------------------------------------ # +# Session context +# ------------------------------------------------------------------ # + + +def log_session_start( + project_dir: str, + ai_provider: str = "", + model: str = "", + timeout: int = 0, + iac_tool: str = "", + discovery_summary: str = "", + extension_version: str = "", +) -> None: + """Log a session header with environment and config context.""" + if _debug_logger is None: + return + lines = [ + f" Python: {sys.version.split()[0]}", + f" OS: {platform.system()} {platform.release()} ({platform.machine()})", + f" Extension: {extension_version or 'unknown'}", + f" Project: {project_dir}", + f" AI Provider: {ai_provider} ({model})" if ai_provider else " AI Provider: (none)", + f" Timeout: {timeout}s" if timeout else " Timeout: default", + f" IaC Tool: {iac_tool}" if iac_tool else " IaC Tool: (none)", + ] + if discovery_summary: + lines.append(f" Discovery: {discovery_summary}") + _debug_logger.info("SESSION_START\n%s", "\n".join(lines)) + + +# ------------------------------------------------------------------ # +# AI calls — the most critical section for troubleshooting +# ------------------------------------------------------------------ # + + +def _truncate(text: str | list, limit: int = _CONTENT_LIMIT) -> str: + """Truncate text for logging, handling both str and multi-modal list.""" + if isinstance(text, list): + # Multi-modal content array — extract text parts + parts = [] + img_count = 0 + for item in text: + if isinstance(item, dict): + if item.get("type") == "text": + parts.append(item.get("text", "")) + elif item.get("type") == "image_url": + img_count += 1 + combined = "\n".join(parts) + suffix = f"\n[{img_count} image(s) attached]" if img_count else "" + if len(combined) > limit: + return combined[:limit] + f"... ({len(combined)} chars total){suffix}" + return combined + suffix + if len(text) > limit: + return text[:limit] + f"... ({len(text)} chars total)" + return text + + +def log_ai_call( + method: str, + *, + system_msgs: int = 0, + system_chars: int = 0, + history_msgs: int = 0, + history_chars: int = 0, + user_content: str | list = "", + model: str = "", + temperature: float = 0.0, + max_tokens: int = 0, +) -> None: + """Log an outgoing AI request with full payload details.""" + if _debug_logger is None: + return + user_chars = ( + len(user_content) + if isinstance(user_content, str) + else sum(len(p.get("text", "")) for p in user_content if isinstance(p, dict)) + ) + total = system_chars + history_chars + user_chars + lines = [ + f" System messages: {system_msgs} msgs, {system_chars:,} chars", + f" History messages: {history_msgs} msgs, {history_chars:,} chars", + f" User message: {user_chars:,} chars", + f" Total payload: {total:,} chars", + f" Model: {model}, Temperature: {temperature}, Max tokens: {max_tokens}", + " --- USER MESSAGE ---", + f" {_truncate(user_content)}", + " --- END USER MESSAGE ---", + ] + _debug_logger.info("AI_CALL %s\n%s", method, "\n".join(lines)) + + +def log_ai_response( + method: str, + *, + elapsed: float = 0.0, + status: int = 0, + response_content: str = "", + prompt_tokens: int = 0, + completion_tokens: int = 0, + total_tokens: int = 0, +) -> None: + """Log an AI response with timing and content.""" + if _debug_logger is None: + return + lines = [ + f" Elapsed: {elapsed:.1f}s", + f" Status: {status}" if status else " Status: (n/a)", + f" Response: {len(response_content):,} chars", + f" Tokens: prompt={prompt_tokens} completion={completion_tokens} total={total_tokens}", + " --- RESPONSE ---", + f" {_truncate(response_content)}", + " --- END RESPONSE ---", + ] + _debug_logger.info("AI_RESPONSE %s\n%s", method, "\n".join(lines)) + + +# ------------------------------------------------------------------ # +# State mutations +# ------------------------------------------------------------------ # + + +def log_state_change(operation: str, **details: Any) -> None: + """Log a state mutation (save, load, mark_item, etc.).""" + if _debug_logger is None: + return + parts = [f" {k}={v}" for k, v in details.items()] + _debug_logger.info("STATE %s\n%s", operation, "\n".join(parts)) + + +# ------------------------------------------------------------------ # +# Decision branches and control flow +# ------------------------------------------------------------------ # + + +def log_flow(method: str, msg: str, **context: Any) -> None: + """Log a decision branch or flow transition.""" + if _debug_logger is None: + return + parts = [f" {msg}"] + for k, v in context.items(): + parts.append(f" {k}={v}") + _debug_logger.info("FLOW %s\n%s", method, "\n".join(parts)) + + +# ------------------------------------------------------------------ # +# Slash commands +# ------------------------------------------------------------------ # + + +def log_command(command: str, **context: Any) -> None: + """Log a slash command invocation.""" + if _debug_logger is None: + return + parts = [f" command={command}"] + for k, v in context.items(): + parts.append(f" {k}={v}") + _debug_logger.info("COMMAND\n%s", "\n".join(parts)) + + +# ------------------------------------------------------------------ # +# Errors +# ------------------------------------------------------------------ # + + +def log_error(method: str, exc: BaseException, **context: Any) -> None: + """Log an error with full traceback.""" + if _debug_logger is None: + return + tb = traceback.format_exception(type(exc), exc, exc.__traceback__) + parts = [f" exception={type(exc).__name__}: {exc}"] + for k, v in context.items(): + parts.append(f" {k}={v}") + parts.append(" --- TRACEBACK ---") + parts.extend(f" {line.rstrip()}" for line in "".join(tb).splitlines()) + parts.append(" --- END TRACEBACK ---") + _debug_logger.error("ERROR %s\n%s", method, "\n".join(parts)) + + +# ------------------------------------------------------------------ # +# Timing +# ------------------------------------------------------------------ # + + +@contextmanager +def log_timer(method: str, msg: str) -> Iterator[None]: + """Context manager that logs elapsed time for a block.""" + if _debug_logger is None: + yield + return + start = time.perf_counter() + _debug_logger.info("TIMER_START %s — %s", method, msg) + try: + yield + finally: + elapsed = time.perf_counter() - start + _debug_logger.info("TIMER_END %s — %s (%.2fs)", method, msg, elapsed) + + +# ------------------------------------------------------------------ # +# Backward-compat aliases (used by existing instrumentation) +# ------------------------------------------------------------------ # + + +def debug(method: str, msg: str, **kwargs: Any) -> None: + """General-purpose debug log (alias for ``log_flow``).""" + log_flow(method, msg, **kwargs) diff --git a/azext_prototype/governance/__init__.py b/azext_prototype/governance/__init__.py index 41fcd4e..f3e2081 100644 --- a/azext_prototype/governance/__init__.py +++ b/azext_prototype/governance/__init__.py @@ -1 +1,20 @@ -"""Governance umbrella — policies, anti-patterns, and design standards.""" +"""Governance umbrella — policies, anti-patterns, and design standards.""" + +from __future__ import annotations + +import logging +from pathlib import Path +from typing import Any + +import yaml + +logger = logging.getLogger(__name__) + + +def safe_load_yaml(path: Path) -> dict[str, Any] | None: + """Load a YAML file, returning None on error (logged as warning).""" + try: + return yaml.safe_load(path.read_text(encoding="utf-8")) or {} + except (OSError, yaml.YAMLError) as exc: + logger.warning("Could not load %s: %s", path.name, exc) + return None diff --git a/azext_prototype/governance/anti_patterns/__init__.py b/azext_prototype/governance/anti_patterns/__init__.py index 314488a..13e71ab 100644 --- a/azext_prototype/governance/anti_patterns/__init__.py +++ b/azext_prototype/governance/anti_patterns/__init__.py @@ -26,7 +26,8 @@ domain: "" description: "" patterns: - - search_patterns: [] + - id: "" + search_patterns: [] safe_patterns: [] warning_message: "" """ @@ -37,7 +38,7 @@ from dataclasses import dataclass, field from pathlib import Path -import yaml +from azext_prototype.governance import safe_load_yaml logger = logging.getLogger(__name__) @@ -51,10 +52,16 @@ class AntiPatternCheck: """A single anti-pattern detection rule.""" + id: str domain: str search_patterns: list[str] = field(default_factory=list) safe_patterns: list[str] = field(default_factory=list) + correct_patterns: list[str] = field(default_factory=list) warning_message: str = "" + description: str = "" + rationale: str = "" + applies_to: list[str] = field(default_factory=list) # agent names + targets: list = field(default_factory=list) # [{"services": [...], "search_patterns": [...], ...}] def load(directory: Path | None = None) -> list[AntiPatternCheck]: @@ -76,30 +83,55 @@ def load(directory: Path | None = None) -> list[AntiPatternCheck]: return _cache for yaml_file in sorted(target.glob("*.yaml")): - try: - data = yaml.safe_load(yaml_file.read_text(encoding="utf-8")) or {} - except (OSError, yaml.YAMLError) as exc: - logger.warning("Could not load anti-pattern file %s: %s", yaml_file.name, exc) - continue - + data = safe_load_yaml(yaml_file) if not isinstance(data, dict): continue domain = data.get("domain", yaml_file.stem) - for entry in data.get("patterns", []): + patterns_list = data.get("patterns", []) + + for idx, entry in enumerate(patterns_list, 1): if not isinstance(entry, dict): continue - search = entry.get("search_patterns", []) - safe = entry.get("safe_patterns", []) + message = entry.get("warning_message", "") + check_id = entry.get("id", f"{domain.upper()}-{idx:03d}") + + check_applies_to = entry.get("applies_to", []) + if not isinstance(check_applies_to, list): + check_applies_to = [] + + targets_raw = entry.get("targets", []) + if isinstance(targets_raw, dict): + targets_raw = [targets_raw] + if not isinstance(targets_raw, list): + targets_raw = [] + + # Aggregate search/safe/correct across all target entries + search: list[str] = [] + safe: list[str] = [] + correct: list[str] = [] + for t in targets_raw: + if isinstance(t, dict): + search.extend(t.get("search_patterns", [])) + safe.extend(t.get("safe_patterns", [])) + correct.extend(t.get("correct_patterns", [])) + if not search or not message: continue + checks.append( AntiPatternCheck( + id=check_id, domain=domain, search_patterns=[s.lower() for s in search], safe_patterns=[s.lower() for s in safe], + correct_patterns=correct, warning_message=message, + description=str(entry.get("description", "")), + rationale=str(entry.get("rationale", "")), + applies_to=check_applies_to, + targets=targets_raw, ) ) @@ -107,22 +139,94 @@ def load(directory: Path | None = None) -> list[AntiPatternCheck]: return _cache -def scan(text: str) -> list[str]: +def scan( + text: str, + iac_tool: str | None = None, + agent_name: str | None = None, + services: list[str] | None = None, +) -> list[str]: """Scan *text* for anti-pattern matches. + Parameters + ---------- + text: + The AI-generated output to scan. + iac_tool: + If provided (e.g., ``"terraform"`` or ``"bicep"``), skip checks + whose ``applies_to`` list is non-empty and does not contain + this tool. Backward compatible — for new format files, use + *agent_name* instead. + agent_name: + If provided, skip checks whose ``applies_to`` list is non-empty + and does not contain this agent name. + services: + If provided, a list of ARM resource type namespaces (e.g., + ``["Microsoft.KeyVault/vaults"]``). Checks whose + ``targets[].services`` list specific namespaces that don't + overlap with *services* are skipped. Checks with no service + targeting (structural checks) run unconditionally. + Returns a list of human-readable warning strings (empty = clean). """ checks = load() warnings: list[str] = [] - lower = text.lower() + + # Strip design notes — these explain WHY choices were made and contain + # terms (e.g., "InstrumentationKey", "Blob Delegator") that trigger + # false positives when scanned out of context. + _DESIGN_MARKERS = ( + "## Key Design Decisions", + "## Design Notes", + "## Key Design Notes", + "## Design Decisions", + ) + scan_text = text + for marker in _DESIGN_MARKERS: + idx = scan_text.find(marker) + if idx >= 0: + scan_text = scan_text[:idx] + break + + lower = scan_text.lower() + + # Map iac_tool shorthand to agent name for filtering + _TOOL_TO_AGENT = {"terraform": "terraform-agent", "bicep": "bicep-agent"} + effective_agent = agent_name or _TOOL_TO_AGENT.get(iac_tool or "", "") + + # Build service namespace set for filtering + svc_set = {s.lower() for s in services} if services else None for check in checks: + # Skip checks not applicable to this agent + if check.applies_to and effective_agent and effective_agent not in check.applies_to: + continue + + # Skip checks not applicable to this stage's services + if svc_set is not None: + check_services: set[str] = set() + for t in check.targets: + if isinstance(t, dict): + check_services.update(s.lower() for s in t.get("services", [])) + # Checks with specific services that don't overlap → skip + if check_services and not (check_services & svc_set): + continue + for pattern in check.search_patterns: - if pattern in lower: + # "!" prefix = absence check — fire if pattern is NOT found. + # Only runs when services context is provided (absence checks + # are meaningless without knowing which service is in scope). + if pattern.startswith("!"): + if svc_set is None: + continue # skip absence checks without service context + absent_term = pattern[1:] + if absent_term not in lower: + warnings.append(f"[{check.id}] {check.warning_message}") + break + elif pattern in lower: # Check safe patterns — if any match, skip this check if check.safe_patterns and any(s in lower for s in check.safe_patterns): continue - warnings.append(check.warning_message) + warnings.append(f"[{check.id}] {check.warning_message}") break # one match per check is enough return warnings diff --git a/azext_prototype/governance/anti_patterns/authentication.yaml b/azext_prototype/governance/anti_patterns/authentication.yaml index 14490cd..abadb64 100644 --- a/azext_prototype/governance/anti_patterns/authentication.yaml +++ b/azext_prototype/governance/anti_patterns/authentication.yaml @@ -1,38 +1,111 @@ -# Anti-pattern detection — Authentication domain -# -# Detects weak or deprecated authentication methods in AI-generated output. - -domain: authentication -description: Authentication method and RBAC assignment detection - -patterns: - - search_patterns: - - "sql authentication" - - "username/password" - - "sql_login" - - "administrator_login_password" - safe_patterns: - - "do not use sql authentication" - - "avoid sql authentication" - - "entra authentication" - warning_message: "SQL authentication with username/password detected — use Microsoft Entra (Azure AD) authentication with managed identity." - - - search_patterns: - - "access_policy {" - - "access_policy =" - - "access policies" - safe_patterns: - - "do not use access policies" - - "avoid access policies" - - "rbac_authorization" - warning_message: "Key Vault access policies detected — use enable_rbac_authorization = true with role assignments instead." - - - search_patterns: - - "\"owner\"" - - "\"contributor\"" - safe_patterns: - - "built-in role" - - "narrowest scope" - - "least privilege" - - "specific role" - warning_message: "Broad role assignment detected (Owner/Contributor) — use the most specific built-in role at the narrowest scope." +kind: anti-pattern +domain: authentication +description: Authentication method detection — ensures managed identity and Entra ID are used +last_updated: '2026-04-04' +patterns: +- id: ANTI-AUTH-001 + description: Detects SQL authentication (username/password) instead of Microsoft Entra authentication + rationale: SQL authentication with passwords is vulnerable to brute force attacks and cannot be audited through Entra ID + conditional access. + warning_message: SQL authentication with username/password detected — use Microsoft Entra (Azure AD) authentication with + managed identity. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers + search_patterns: + - sql authentication + - username/password + - sql_login + - administrator_login_password + safe_patterns: + - do not use sql authentication + - avoid sql authentication + - entra authentication + - sql authentication is fully disabled + - sql authentication is disabled + - sql authentication must be disabled + - azureadonlyauthentication = true + - azureadonlyauthentications + correct_patterns: + - azureADOnlyAuthentication = true + - '# Use Microsoft Entra authentication with managed identity' +- id: ANTI-AUTH-002 + description: Detects Key Vault access policy model instead of RBAC authorization + rationale: Access policies provide coarse-grained control and cannot leverage Entra ID conditional access, PIM, or per-identity + audit trails. + warning_message: Key Vault using access policies — switch to RBAC authorization model (enableRbacAuthorization = true). + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.KeyVault/vaults + search_patterns: + - access_policy { + - access_policy = + - access policies + safe_patterns: + - do not use access policies + - avoid access policies + - rbac_authorization + - enableRbacAuthorization = true + correct_patterns: + - enableRbacAuthorization = true + - '# Use RBAC authorization model, not access policies' +- id: ANTI-AUTH-003 + description: Detects SAS token usage where managed identity with RBAC should be used + rationale: SAS tokens are time-limited shared secrets that cannot be revoked individually and bypass RBAC audit trails. + warning_message: SAS token detected — use managed identity with appropriate RBAC role instead. + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Storage/storageAccounts + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + search_patterns: + - shared_access_policy + - sas_token + - sas_policy + - generate_sas + - listAccountSas + - listServiceSas + - SharedAccessSignature + safe_patterns: + - do not use sas + - avoid sas token + - managed identity + - DefaultAzureCredential + correct_patterns: + - '# Use managed identity with RBAC role assignment' + - DefaultAzureCredential() +- id: ANTI-AUTH-004 + description: Detects Cosmos DB local/key authentication when Entra RBAC should be used + rationale: Cosmos DB key authentication uses shared master keys that grant full access — Entra RBAC provides per-identity + scoping and audit. + warning_message: Cosmos DB local authentication detected — disable local auth and use Entra RBAC with sqlRoleAssignments. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + search_patterns: + - primary_key + - primary_readonly_key + - listKeys( + - AccountKey= + safe_patterns: + - disableLocalAuth = true + - DefaultAzureCredential + - do not use keys + correct_patterns: + - disableLocalAuth = true + - '# Use Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments for data-plane RBAC' diff --git a/azext_prototype/governance/anti_patterns/bicep_structure.yaml b/azext_prototype/governance/anti_patterns/bicep_structure.yaml new file mode 100644 index 0000000..c73a139 --- /dev/null +++ b/azext_prototype/governance/anti_patterns/bicep_structure.yaml @@ -0,0 +1,124 @@ +kind: anti-pattern +domain: bicep_structure +description: Bicep file structure, module conventions, and deployment script patterns +last_updated: '2026-04-04' +patterns: +- id: ANTI-BCS-001 + description: Detects inline resource definitions instead of Bicep module references + rationale: Inline resources in main.bicep create monolithic templates that are hard to test, reuse, and review. + warning_message: Inline resource detected — use module references (module './modules/.bicep') for all resources. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - 'resource ' + safe_patterns: + - 'module ' + - modules/ + - existing + correct_patterns: + - module identity './modules/identity.bicep' + - module monitoring './modules/monitoring.bicep' +- id: ANTI-BCS-002 + description: Detects listKeys() or listSas() calls which expose secrets in deployment history + rationale: listKeys() exposes secrets in ARM deployment outputs and template history; managed identity with RBAC avoids + secret exposure entirely. + warning_message: listKeys()/listSas() detected — use managed identity with RBAC role assignments instead. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - listKeys( + - listAccountSas( + - listServiceSas( + safe_patterns: + - Microsoft.ManagedIdentity/userAssignedIdentities + - managedIdentity + - 'identity: {' + correct_patterns: + - Microsoft.ManagedIdentity/userAssignedIdentities + - 'identity: { type: ''UserAssigned'' }' +- id: ANTI-BCS-003 + description: Detects hardcoded resource names in Bicep instead of parameterized naming + rationale: Hardcoded resource names prevent reuse across environments and violate naming convention standards. + warning_message: Hardcoded resource name detected — use variables or parameters for resource naming. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - 'name: ''' + safe_patterns: + - 'name: ''${' + - 'name: resourceName' + - 'name: storageAccountName' + - var resourceName = + correct_patterns: + - var storageAccountName = '${prefix}-st-${suffix}' + - 'name: storageAccountName' +- id: ANTI-BCS-004 + description: Detects Bicep parameters missing @description decorator + rationale: Missing parameter descriptions make templates harder to use and prevent proper validation during deployment review. + warning_message: Bicep parameter missing @description decorator — add @description() to all parameters. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - 'param ' + safe_patterns: + - '@description(' + - '@Description(' + correct_patterns: + - '@description(''The Azure region for all resources'')' + - param location string +- id: ANTI-BCS-005 + description: Detects Bicep modules without output declarations for downstream consumers + rationale: Missing outputs prevent downstream modules from referencing this module's resources, breaking the deployment + chain. + warning_message: Bicep module missing output declarations — add outputs for resources consumed by downstream modules. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - 'module ' + safe_patterns: + - 'output ' + correct_patterns: + - output storageAccountId string = storage.outputs.id + - output identityPrincipalId string = identity.outputs.principalId +- id: ANTI-BCS-006 + description: Detects Bicep deployment scripts without error handling (set -euo pipefail) + rationale: Deployment scripts without error handling silently continue after failures, leading to partial and inconsistent + deployments. + warning_message: Deployment script missing error handling — add set -euo pipefail. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - az deployment group create + safe_patterns: + - set -euo pipefail + - set -e + correct_patterns: + - set -euo pipefail + - '#!/bin/bash' +- id: ANTI-BCS-007 + description: Detects outdated Bicep API versions (pre-2023) that may lack features or have breaking changes + rationale: Old API versions miss security features, property changes, and may be deprecated by Azure. + warning_message: Outdated API version detected — use 2023 or 2024 API versions. + applies_to: + - bicep-agent + targets: + - services: [] + search_patterns: + - '@2021-' + - '@2020-' + - '@2019-' + correct_patterns: + - '@2023-' + - '@2024-' diff --git a/azext_prototype/governance/anti_patterns/completeness.yaml b/azext_prototype/governance/anti_patterns/completeness.yaml index 838305c..ceece45 100644 --- a/azext_prototype/governance/anti_patterns/completeness.yaml +++ b/azext_prototype/governance/anti_patterns/completeness.yaml @@ -1,70 +1,233 @@ -# Anti-pattern detection — Completeness domain -# -# Detects structural gaps, incomplete scripts, and missing companion -# resources in AI-generated output. These patterns catch issues that -# indicate the generated code is not deployment-ready. - -domain: completeness -description: Structural gaps, incomplete scripts, and missing companion resources - -patterns: - - search_patterns: - - "local_authentication_disabled = true" - - "local_auth_disabled = true" - - "disableLocalAuth: true" - - "shared_access_key_enabled = false" - - "allowSharedKeyAccess: false" - safe_patterns: - - "azurerm_user_assigned_identity" - - "azurerm_role_assignment" - - "azurerm_cosmosdb_sql_role_assignment" - - "Microsoft.ManagedIdentity/userAssignedIdentities" - - "roleAssignments" - - "user_assigned_identity" - warning_message: "Local/key-based authentication is disabled but no managed identity or RBAC role assignment found in the same stage. Applications will be unable to authenticate." - - - search_patterns: - - "echo -e \"${YELLOW}" - - "echo -e \"${RED}" - - "echo -e \"${GREEN}" - - "echo \"" - safe_patterns: - - "echo \"\"" - warning_message: "Possible incomplete echo statement in deploy script — verify all strings are properly closed." - - - search_patterns: - - "terraform_remote_state" - safe_patterns: [] - warning_message: "" - - - search_patterns: - - "data \"azurerm_resource_group\"" - - "data \"azurerm_log_analytics_workspace\"" - - "data \"azurerm_key_vault\"" - safe_patterns: - - "terraform_remote_state" - - "data.terraform_remote_state" - - "var." - warning_message: "Data source references existing resource by hardcoded name — use terraform_remote_state or variables to reference resources from prior stages." - - - search_patterns: - - "versions.tf" - safe_patterns: - - "providers.tf" - warning_message: "Terraform config uses versions.tf — this WILL cause deployment failure. Provider configuration (terraform {}, required_providers, backend) must be in providers.tf only. Using both files causes duplicate required_providers blocks that break terraform init. Remove versions.tf and consolidate into providers.tf." - - - search_patterns: - - "var.tfstate_storage_account" - - "var.backend_storage_account" - - "var.state_storage_account" - safe_patterns: [] - warning_message: "Backend config uses variable references — Terraform does not support variables in backend blocks. Use literal values or omit the backend to use local state." - - - search_patterns: - - "storage_account_name = \"\"" - - "container_name = \"\"" - - "key = \"\"" - - "resource_group_name = \"\"" - safe_patterns: - - "backend \"local\"" - warning_message: "Backend config has empty required fields — terraform init will fail. Either provide literal values or omit the backend block to use local state." +kind: anti-pattern +domain: completeness +description: Structural gaps, incomplete scripts, and missing companion resources +last_updated: '2026-04-04' +patterns: +- id: ANTI-COMP-001 + description: Detects local auth disabled without a companion managed identity and role assignment + rationale: Disabling local auth without providing an alternative identity causes authentication failures at runtime. + warning_message: Local auth disabled but no managed identity or role assignment detected — include both when disabling local + auth. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts + - Microsoft.ContainerRegistry/registries + - Microsoft.OperationalInsights/workspaces + search_patterns: + - local_authentication_disabled = true + - local_auth_disabled = true + - 'disableLocalAuth: true' + - shared_access_key_enabled = false + - 'allowSharedKeyAccess: false' + safe_patterns: + - azurerm_user_assigned_identity + - azurerm_role_assignment + - Microsoft.ManagedIdentity/userAssignedIdentities + - roleAssignments + - user_assigned_identity + correct_patterns: + - Microsoft.ManagedIdentity/userAssignedIdentities + - Microsoft.Authorization/roleAssignments + - '# Include managed identity AND role assignment when disabling local auth' +- id: ANTI-COMP-002 + description: Detects lowercase color variable names in deploy.sh scripts (should be UPPERCASE) + rationale: Bash convention uses UPPERCASE for constants; lowercase color variables conflict with common variable names. + warning_message: Deploy script uses lowercase color variables — use UPPERCASE (YELLOW, RED, GREEN, NC). + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: [] + search_patterns: + - echo -e "${yellow} + - echo -e "${red} + - echo -e "${green} + safe_patterns: + - ${NC} + - ${YELLOW} + - ${RED} + - ${GREEN} + correct_patterns: + - echo -e "${YELLOW}message${NC}" + - echo -e "${RED}message${NC}" + - echo -e "${GREEN}message${NC}" +- id: ANTI-COMP-003 + description: Detects azurerm data source lookups that should use terraform_remote_state or input variables + rationale: azurerm data sources require the azurerm provider which is not used in this project — use remote state or variables + instead. + warning_message: azurerm data source detected — use terraform_remote_state or input variables to reference prior-stage resources. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - data "azurerm_resource_group" + - data "azurerm_log_analytics_workspace" + - data "azurerm_key_vault" + - data "azurerm_storage_account" + - data "azurerm_container_registry" + safe_patterns: + - terraform_remote_state + - data.terraform_remote_state + - var. + correct_patterns: + - data.terraform_remote_state.stage_name.outputs.resource_id + - var.resource_group_name + - '# Reference prior-stage resources via remote state or input variables' +- id: ANTI-COMP-004 + description: Detects versions.tf file which conflicts with the providers.tf convention + rationale: This project consolidates terraform {}, required_providers, and backend into providers.tf — a separate versions.tf + causes confusion. + warning_message: versions.tf detected — consolidate terraform {}, required_providers, and backend into providers.tf only. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - versions.tf + safe_patterns: + - providers.tf + correct_patterns: + - providers.tf + - '# Consolidate terraform {}, required_providers, and backend into providers.tf only' +- id: ANTI-COMP-005 + description: Detects variables used in Terraform backend blocks which do not support variable interpolation + rationale: Terraform backend configuration blocks cannot use variables, locals, or data sources — only literal values are + supported. + warning_message: Variable reference in backend block — backend blocks only support literal values, not variables. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - var.tfstate_storage_account + - var.backend_storage_account + - var.state_storage_account + correct_patterns: + - storage_account_name = "mystorageaccount" + - '# Use literal values in backend blocks — variables are not supported' + - backend "local" {} +- id: ANTI-COMP-006 + description: Detects empty string values in Terraform backend configuration + rationale: Empty backend configuration values cause Terraform init failures or silent fallback to defaults. + warning_message: Empty backend configuration values detected — provide literal values or use local backend. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - storage_account_name = "" + - container_name = "" + - key = "" + - resource_group_name = "" + safe_patterns: + - backend "local" + correct_patterns: + - storage_account_name = "tfstate12345" + - container_name = "tfstate" + - key = "stage-name.tfstate" + - backend "local" {} +- id: ANTI-COMP-007 + description: Detects hardcoded resource names using naming convention prefixes instead of variables + rationale: Hardcoded names with zone prefixes (zd-, pm-, pc-) break when naming conventions change or resources are reused + across environments. + warning_message: Hardcoded resource name with naming convention prefix detected — use variables or remote state outputs. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: [] + search_patterns: + - queueName = "zd- + - queueName = "pi- + - queueName = "pm- + - queueName = "pc- + - name = "zdacr + - name = "zdst + - resource_group_name = "zd-rg- + - resource_group_name = "pi-rg- + - resource_group_name = "pm-rg- + safe_patterns: + - var. + - local. + - data.terraform_remote_state + - data.azapi_resource + correct_patterns: + - data.terraform_remote_state.stage.outputs.queue_name + - var.resource_group_name + - local.resource_group_name +- id: ANTI-COMP-008 + description: Detects Storage Blob Delegator role which only grants delegation key access, not blob data access + rationale: Storage Blob Delegator only grants User Delegation Key access — applications need Storage Blob Data Contributor + for actual blob read/write. + warning_message: Storage Blob Delegator role detected — use Storage Blob Data Contributor (ba92f5b4) for blob data access. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + search_patterns: + - storage blob delegator + safe_patterns: + - storage blob data contributor + - storage blob data reader + correct_patterns: + - Storage Blob Data Contributor + - '# ba92f5b4-2d11-453d-a403-e96b0029c9fe' +- id: ANTI-COMP-009 + description: Detects non-existent capacityMode property on Cosmos DB — use capabilities instead + rationale: The Cosmos DB ARM schema does not have a capacityMode property. Setting it is silently ignored and serverless + mode is not activated. + warning_message: capacityMode does not exist in Cosmos DB ARM schema — use capabilities = [{ name = "EnableServerless" }] + instead. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + search_patterns: + - capacitymode = "serverless" + - capacitymode + safe_patterns: + - enableserverless + correct_patterns: + - capabilities = [{ name = "EnableServerless" }] +- id: ANTI-COMP-010 + description: Detects string interpolation for blob service diagnostic settings parent_id instead of a child resource reference + rationale: String interpolation for ARM child resource IDs is fragile and breaks when the resource ID format changes. + warning_message: Use an azapi_resource for blobServices/default and reference its .id for diagnostic settings parent_id. + applies_to: + - terraform-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + search_patterns: + - /blobservices/default + safe_patterns: + - azapi_resource + - blob_service + correct_patterns: + - parent_id = azapi_resource.blob_service.id +- id: ANTI-COMP-011 + description: Detects azapi_resource blocks that may be missing parent_id — required on every azapi_resource + rationale: The azapi provider requires parent_id on all resources. Omitting it causes terraform plan failure. + For resource groups, parent_id is /subscriptions/${var.subscription_id}. For child resources, parent_id + is the parent resource ID. + warning_message: azapi_resource may be missing parent_id — every azapi_resource MUST have parent_id set. + applies_to: + - terraform-agent + targets: + - services: + - Microsoft.Resources/resourceGroups + search_patterns: + - '!parent_id' + correct_patterns: + - parent_id = "/subscriptions/${var.subscription_id}" diff --git a/azext_prototype/governance/anti_patterns/containers.yaml b/azext_prototype/governance/anti_patterns/containers.yaml index 3717bb9..8f172cb 100644 --- a/azext_prototype/governance/anti_patterns/containers.yaml +++ b/azext_prototype/governance/anti_patterns/containers.yaml @@ -1,27 +1,89 @@ -# Anti-pattern detection — Containers domain -# -# Detects insecure container and registry configurations in -# AI-generated output. - -domain: containers -description: Container Apps, ACR, and container runtime configuration detection - -patterns: - - search_patterns: - - "environment_variable" - - "env_var" - safe_patterns: - - "key vault" - - "keyvault" - - "managed identity" - - "secret_ref" - - "secretref" - warning_message: "Secrets in environment variables detected — use Key Vault references with managed identity instead." - - - search_patterns: - - "admin_user_enabled = true" - - "acrpush" - safe_patterns: - - "managed identity" - - "acrpull" - warning_message: "Container registry admin credentials detected — use managed identity with AcrPull role assignment." +kind: anti-pattern +domain: containers +description: Container Apps, ACR, and container runtime configuration detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-CONT-001 + description: Detects secrets passed as plain environment variables instead of Key Vault secret references + rationale: Plain environment variables expose secrets in Container App revision metadata and ARM deployment history. + warning_message: Secret in environment variable — use Key Vault references with managed identity instead. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + search_patterns: + - environment_variable + - env_var + safe_patterns: + - key vault + - keyvault + - managed identity + - secret_ref + - secretref + - secretRef + - keyVaultUrl + correct_patterns: + - secretRef + - '# Use Key Vault references with managed identity' +- id: ANTI-CONT-002 + description: Detects container registry admin user enabled instead of managed identity with AcrPull + rationale: Admin credentials are shared secrets that cannot be scoped per-service; managed identity with AcrPull provides + per-identity audit. + warning_message: Container registry admin user enabled — disable admin and use managed identity with AcrPull role. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ContainerRegistry/registries + search_patterns: + - admin_user_enabled = true + - adminUserEnabled = true + correct_patterns: + - admin_user_enabled = false + - adminUserEnabled = false + - '# Use managed identity with AcrPull role assignment' +- id: ANTI-CONT-003 + description: Detects Container App without UserAssigned managed identity for ACR image pull + rationale: SystemAssigned identity alone causes image pull failures on first provision because the identity doesn't exist + when ACR pull is attempted. + warning_message: Container App needs UserAssigned identity (or SystemAssigned,UserAssigned) for ACR image pull — SystemAssigned + alone fails on first deploy. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + search_patterns: + - microsoft.app/containerapps + safe_patterns: + - userassignedidentities + - systemassigned, userassigned + correct_patterns: + - type = "SystemAssigned, UserAssigned" + - identity.userAssignedIdentities +- id: ANTI-CONT-004 + description: Detects latest tag on container images instead of immutable version or SHA tags + rationale: The :latest tag is mutable and non-deterministic — different nodes may pull different images, causing inconsistent + behavior. + warning_message: Container image uses :latest tag — use a specific version tag or SHA digest for reproducible deployments. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerRegistry/registries + search_patterns: + - :latest + - image:latest + safe_patterns: + - '# placeholder, will be updated by CI/CD' + - :${var. + correct_patterns: + - image = "myregistry.azurecr.io/myapp:v1.2.3" + - image = "myregistry.azurecr.io/myapp@sha256:abc123" diff --git a/azext_prototype/governance/anti_patterns/cost.yaml b/azext_prototype/governance/anti_patterns/cost.yaml index 83cff45..99bba00 100644 --- a/azext_prototype/governance/anti_patterns/cost.yaml +++ b/azext_prototype/governance/anti_patterns/cost.yaml @@ -1,37 +1,78 @@ -# Anti-pattern detection — Cost domain -# -# Detects potential cost overruns and oversized configurations in -# AI-generated output. These are recommendations, not hard rules — -# users may choose larger SKUs for production workloads. - -domain: cost -description: Oversized SKUs, missing autoscale, and cost-inefficient configurations - -patterns: - - search_patterns: - - "sku_name = \"p1v3\"" - - "sku_name = \"p2v3\"" - - "sku_name = \"p3v3\"" - - "sku_name = \"premium\"" - safe_patterns: - - "production" - - "high availability" - - "performance requirement" - warning_message: "Premium SKU detected — consider Standard or Basic tier for POC workloads to reduce cost." - - - search_patterns: - - "min_replicas = 1" - - "minimum_instance_count = 1" - safe_patterns: - - "production" - - "always-on" - - "high availability" - warning_message: "Minimum instances set to 1 — consider 0 for dev/test to avoid idle costs." - - - search_patterns: - - "reserved_capacity" - - "reserved_instance" - safe_patterns: - - "production" - - "cost analysis" - warning_message: "Reserved capacity in POC — reserved instances lock in commitment; use pay-as-you-go for prototypes." +kind: anti-pattern +domain: cost +description: Oversized SKUs, missing autoscale, and cost-inefficient configurations for POC +last_updated: '2026-04-04' +patterns: +- id: ANTI-COST-001 + description: Detects Premium or Enterprise tier SKUs that are excessive for POC workloads + rationale: Premium and Enterprise SKUs are 10-50x more expensive than Basic/Standard tiers and rarely needed for POC validation. + warning_message: Premium/Enterprise SKU detected — use Basic or Standard tier for POC unless explicitly required. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Web/sites + - Microsoft.Web/serverfarms + search_patterns: + - sku_name = "p1v3" + - sku_name = "p2v3" + - sku_name = "p3v3" + safe_patterns: + - sku_name = var. + - sku_name = "B1" + - sku_name = "S1" + - sku_name = "Y1" + correct_patterns: + - sku_name = "B1" + - sku_name = "S1" + - sku_name = "Y1" + - services: + - Microsoft.Cache/redis + - Microsoft.ServiceBus/namespaces + search_patterns: + - sku_name = "premium" + safe_patterns: + - premium is required for + - sku_name = var. + correct_patterns: + - name = "Basic" + - name = "Standard" +- id: ANTI-COST-002 + description: Detects always-on minimum replicas for Container Apps in POC where scale-to-zero is preferred + rationale: Minimum replica count of 1+ means the app runs continuously even with no traffic, consuming resources unnecessarily. + warning_message: min_replicas > 0 detected — use min_replicas = 0 for scale-to-zero in POC. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + search_patterns: + - min_replicas = 1 + - minimum_instance_count = 1 + safe_patterns: + - min_replicas = var. + - '# always-on required' + correct_patterns: + - min_replicas = 0 + - minReplicas = 0 +- id: ANTI-COST-003 + description: Detects reserved capacity or reserved instance commitments inappropriate for POC + rationale: Reserved capacity requires 1-3 year commitments — POC workloads should use pay-as-you-go pricing. + warning_message: Reserved capacity/instance detected — use pay-as-you-go pricing for POC workloads. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: [] + search_patterns: + - reserved_capacity + - reserved_instance + safe_patterns: + - '# reserved capacity justified' + - reserved_capacity = var. + correct_patterns: + - '# Use pay-as-you-go pricing for POC workloads' diff --git a/azext_prototype/governance/anti_patterns/encryption.yaml b/azext_prototype/governance/anti_patterns/encryption.yaml index 6378a89..8f8dce2 100644 --- a/azext_prototype/governance/anti_patterns/encryption.yaml +++ b/azext_prototype/governance/anti_patterns/encryption.yaml @@ -1,29 +1,69 @@ -# Anti-pattern detection — Encryption domain -# -# Detects disabled or weak encryption settings in AI-generated output. - -domain: encryption -description: TLS enforcement, encryption at rest, and transport security detection - -patterns: - - search_patterns: - - "min_tls_version = \"1.0\"" - - "min_tls_version = \"1.1\"" - - "minimum_tls_version = \"1.0\"" - - "minimum_tls_version = \"1.1\"" - - "tls1_0" - - "tls1_1" - safe_patterns: [] - warning_message: "Outdated TLS version detected — enforce minimum TLS 1.2 for all connections." - - - search_patterns: - - "https_only = false" - - "https_required = false" - safe_patterns: [] - warning_message: "HTTPS enforcement disabled — set https_only = true to redirect all HTTP to HTTPS." - - - search_patterns: - - "ssl_enforcement_enabled = false" - - "ssl_minimal_tls_version_enforced = \"tldisabled\"" - safe_patterns: [] - warning_message: "SSL enforcement disabled — enable SSL enforcement with TLS 1.2 minimum." +kind: anti-pattern +domain: encryption +description: TLS enforcement, encryption at rest, and transport security detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-ENC-001 + description: Detects TLS version below 1.2 which has known vulnerabilities + rationale: TLS 1.0 and 1.1 have known vulnerabilities (BEAST, POODLE) and are deprecated by compliance frameworks. + warning_message: TLS version below 1.2 detected — set minimum TLS version to 1.2. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers + - Microsoft.Cache/redis + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.DocumentDB/databaseAccounts + search_patterns: + - min_tls_version = "1.0" + - min_tls_version = "1.1" + - minimum_tls_version = "1.0" + - minimum_tls_version = "1.1" + - tls1_0 + - tls1_1 + correct_patterns: + - min_tls_version = "1.2" + - minimum_tls_version = "1.2" + - minimalTlsVersion = "1.2" + - minimumTlsVersion = "TLS1_2" +- id: ANTI-ENC-002 + description: Detects HTTPS disabled on App Service or Function Apps + rationale: HTTP transmits data in plaintext, exposing credentials and data to network interception. + warning_message: HTTPS not enforced — set https_only = true. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + search_patterns: + - https_only = false + - https_required = false + correct_patterns: + - https_only = true + - httpsOnly = true +- id: ANTI-ENC-003 + description: Detects SSL enforcement disabled on database servers + rationale: Disabled SSL allows unencrypted database connections, exposing query data and credentials in transit. + warning_message: SSL enforcement disabled — enable SSL and set minimum TLS 1.2. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.DBforPostgreSQL/flexibleServers + search_patterns: + - ssl_enforcement_enabled = false + - ssl_minimal_tls_version_enforced = "tldisabled" + correct_patterns: + - ssl_enforcement_enabled = true + - sslEnforcement = "Enabled" + - ssl_minimal_tls_version_enforced = "TLS1_2" + - minimalTlsVersion = "TLS1_2" diff --git a/azext_prototype/governance/anti_patterns/monitoring.yaml b/azext_prototype/governance/anti_patterns/monitoring.yaml index 261b6dd..fc17e58 100644 --- a/azext_prototype/governance/anti_patterns/monitoring.yaml +++ b/azext_prototype/governance/anti_patterns/monitoring.yaml @@ -1,20 +1,68 @@ -# Anti-pattern detection — Monitoring domain -# -# Detects missing or disabled observability configurations in AI-generated output. - -domain: monitoring -description: Logging, diagnostics, and observability gap detection - -patterns: - - search_patterns: - - "retention_in_days = 0" - - "retention_days = 0" - safe_patterns: [] - warning_message: "Log retention set to 0 days — configure at least 30 days for compliance and incident investigation." - - - search_patterns: - - "enabled_log_category = []" - - "logs_enabled = false" - - "metrics_enabled = false" - safe_patterns: [] - warning_message: "Diagnostic logs or metrics disabled — enable logging for all PaaS resources." +kind: anti-pattern +domain: monitoring +description: Logging, diagnostics, and observability gap detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-MON-001 + description: Detects zero retention period for diagnostic logs or metrics + rationale: Zero retention means logs are immediately discarded, making incident investigation impossible. + warning_message: Log retention set to 0 days — set retention_in_days to at least 30 for POC. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Insights/diagnosticSettings + - Microsoft.OperationalInsights/workspaces + search_patterns: + - retention_in_days = 0 + - retention_days = 0 + correct_patterns: + - retention_in_days = 30 + - retentionInDays = 30 +- id: ANTI-MON-002 + description: Detects disabled logging or metrics in diagnostic settings + rationale: Disabled log or metric collection creates blind spots where failures and security events go undetected. + warning_message: Logging or metrics disabled in diagnostic settings — enable both for observability. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Insights/diagnosticSettings + search_patterns: + - enabled_log_category = [] + - logs_enabled = false + - metrics_enabled = false + correct_patterns: + - logs_enabled = true + - metrics_enabled = true + - '# Enable diagnostic settings for all PaaS resources' +- id: ANTI-MON-003 + description: Detects deprecated InstrumentationKey usage instead of ConnectionString for Application Insights + rationale: InstrumentationKey is deprecated by Microsoft. ConnectionString is the supported integration point and includes + region routing. + warning_message: InstrumentationKey detected — use ConnectionString (APPLICATIONINSIGHTS_CONNECTION_STRING) instead. + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Insights/components + - Microsoft.App/containerApps + - Microsoft.Web/sites + search_patterns: + - instrumentation_key + - instrumentationkey + safe_patterns: + - '# deprecated' + - use connection_string + - do not use instrumentationkey + - connectionstring + correct_patterns: + - connection_string + - APPLICATIONINSIGHTS_CONNECTION_STRING + - '# Use connection_string instead of InstrumentationKey' diff --git a/azext_prototype/governance/anti_patterns/networking.yaml b/azext_prototype/governance/anti_patterns/networking.yaml index 3e21042..01cb469 100644 --- a/azext_prototype/governance/anti_patterns/networking.yaml +++ b/azext_prototype/governance/anti_patterns/networking.yaml @@ -1,47 +1,228 @@ -# Anti-pattern detection — Networking domain -# -# Detects overly permissive network configurations, missing private -# endpoints, and public exposure in AI-generated output. - -domain: networking -description: Network isolation, firewall rules, and public exposure detection - -patterns: - - search_patterns: - - "public_network_access_enabled = true" - - "public_network_access = \"enabled\"" - - "publicnetworkaccess = \"enabled\"" - safe_patterns: [] - warning_message: "Public network access is enabled — disable public access and use private endpoints or service endpoints." - - - search_patterns: - - "0.0.0.0/0" - - "0.0.0.0-255.255.255.255" - safe_patterns: - - "do not allow 0.0.0.0" - - "avoid 0.0.0.0" - warning_message: "Overly permissive network rule detected (0.0.0.0/0) — use specific IP ranges or service tags." - - - search_patterns: - - "ingress_type = \"external\"" - - "external_enabled = true" - safe_patterns: - - "apim" - - "api management" - - "front door" - - "application gateway" - warning_message: "Direct external ingress detected — consider using API Management or Front Door as a gateway." - - - search_patterns: - - "vnet_route_all_enabled = false" - - "virtual_network_subnet_id = null" - safe_patterns: [] - warning_message: "VNET integration disabled — enable VNET integration for backend connectivity to private resources." - - - search_patterns: - - "ip_restriction = []" - - "scm_ip_restriction = []" - safe_patterns: - - "allow all" - - "development" - warning_message: "Empty IP restrictions — configure IP restrictions or use VNET integration to limit access." +kind: anti-pattern +domain: networking +description: Network isolation, firewall rules, and public exposure detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-NET-001 + description: Detects public network access enabled on PaaS services that should be private-only + rationale: Public network access exposes service data planes to internet-based attacks; all PaaS services should disable + public access and use private endpoints. + warning_message: Public network access is enabled — disable public access and use private endpoints. This applies to ALL + environments including POC. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.KeyVault/vaults + - Microsoft.Cache/redis + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Search/searchServices + - Microsoft.CognitiveServices/accounts + - Microsoft.ContainerRegistry/registries + - Microsoft.OperationalInsights/workspaces + - Microsoft.Insights/components + search_patterns: + - public_network_access_enabled = true + - public_network_access = "enabled" + - publicnetworkaccess = "enabled" + - publicnetworkaccessforingestion = "enabled" + - publicnetworkaccessforquery = "enabled" + safe_patterns: + - public_network_access_enabled = false + - publicnetworkaccess = "disabled" + - publicnetworkaccessforingestion = "disabled" + - publicnetworkaccessforquery = "disabled" + - public_network_access_enabled = var. + correct_patterns: + - publicNetworkAccess = "Disabled" + - public_network_access_enabled = false + - publicNetworkAccessForIngestion = "Disabled" + - publicNetworkAccessForQuery = "Disabled" +- id: ANTI-NET-002 + description: Detects overly permissive network rules using 0.0.0.0/0 CIDR (allow all internet traffic) + rationale: Allowing all internet traffic (0.0.0.0/0) in NSG or firewall rules defeats network segmentation and exposes resources + to attack. + warning_message: Overly permissive network rule detected (0.0.0.0/0) — use specific IP ranges or service tags instead. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/networkSecurityGroups + - Microsoft.Network/azureFirewalls + search_patterns: + - 0.0.0.0/0 + - 0.0.0.0-255.255.255.255 + safe_patterns: + - do not allow 0.0.0.0 + - avoid 0.0.0.0 + - '# outbound to internet' + - destinationAddressPrefix = "Internet" +- id: ANTI-NET-003 + description: Detects Container Apps or App Services with direct external ingress without an API gateway + rationale: Direct external ingress bypasses WAF, rate limiting, and centralized authentication that API Management or Front + Door provides. + warning_message: Direct external ingress detected — consider using API Management or Front Door as a gateway for production. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + search_patterns: + - ingress_type = "external" + - external_enabled = true + - external = true + safe_patterns: + - apim + - api management + - front door + - application gateway +- id: ANTI-NET-004 + description: Detects VNet integration disabled or missing on compute resources that need private backend connectivity + rationale: Without VNet integration, compute resources cannot access private endpoints or backend services on private networks. + warning_message: VNet integration disabled or missing — enable VNet integration for backend connectivity to private resources. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/managedEnvironments + search_patterns: + - vnet_route_all_enabled = false + - virtual_network_subnet_id = null + safe_patterns: + - virtual_network_subnet_id = var. + - subnetId = +- id: ANTI-NET-005 + description: Detects empty IP restriction lists on App Service or Function Apps, allowing unrestricted access + rationale: Empty IP restrictions allow all internet traffic to reach the app directly, bypassing network controls. + warning_message: Empty IP restrictions — configure IP restrictions or use VNet integration to limit access. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + search_patterns: + - ip_restriction = [] + - scm_ip_restriction = [] + safe_patterns: + - ip_restriction = var. +- id: ANTI-NET-006 + description: Detects private endpoint referencing a VNet as its privateLinkServiceId — VNets are not valid Private Link + targets + rationale: Private endpoints connect to specific Azure PaaS services, not VNets. ARM will reject this with HTTP 400. + warning_message: Private endpoint references a VNet as its privateLinkServiceId — VNets are not valid Private Link targets. + ARM will reject this with HTTP 400. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/privateEndpoints + search_patterns: + - privateLinkServiceId = azapi_resource.vnet + - privateLinkServiceId = azapi_resource.virtual_network + - private_link_service_id = azurerm_virtual_network + correct_patterns: + - '# Private endpoints target specific PaaS services (e.g., Microsoft.Sql/servers), not VNets' +- id: ANTI-NET-007 + description: Detects diagnostic settings on VNets or NSGs using log categories — these resources only support AllMetrics + rationale: VNets and NSGs do not support log category groups. Using categoryGroup = "allLogs" causes ARM HTTP 400 validation + errors. + warning_message: VNet/NSG diagnostic settings must use category = "AllMetrics" only — log categories are not supported and + cause ARM errors. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/virtualNetworks + - Microsoft.Network/networkSecurityGroups + search_patterns: + - diag_vnet + - diag_nsg + - diagnostics_vnet + - diagnostics_nsg + safe_patterns: + - category = "AllMetrics" + correct_patterns: + - category = "AllMetrics" + - '# VNets and NSGs only support AllMetrics, not log categories' +- id: ANTI-NET-008 + description: Detects diagnostic settings created for NSG resources — NSGs do not support any diagnostic categories + rationale: NSGs do not support diagnostic settings at all (no logs, no metrics). The ARM API will reject with HTTP 400. + warning_message: NSGs do NOT support diagnostic settings — remove the diagnostic settings resource entirely. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/networkSecurityGroups + search_patterns: + - nsg_pe_diag + - nsg_aca_diag + - nsg_diag + safe_patterns: + - '# NSGs do not support diagnostic settings' + correct_patterns: + - '# NSGs do NOT support diagnostic settings — no log or metric categories' +- id: ANTI-NET-009 + description: Detects oversized VNet or subnet CIDR blocks (/8 or /16) inappropriate for POC workloads + rationale: A /16 allocates 65,536 IPs and a /8 allocates 16 million — wildly excessive for POC workloads that typically + need fewer than 1,000 addresses. + warning_message: Oversized address space detected — use /22 to /24 for POC subnets, /20 to /22 for VNets. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/virtualNetworks + search_patterns: + - /8" + - /16" + - 10.0.0.0/8 + - 10.0.0.0/16 + - 172.16.0.0/12 + safe_patterns: + - /20 + - /21 + - /22 + - /23 + - /24 + - /27 + correct_patterns: + - addressPrefix = "10.0.0.0/22" + - '# Use /22-/24 for subnets, /20-/22 for VNets in POC' +- id: ANTI-NET-010 + description: Detects wildcard (*) source or destination in NSG security rules allowing unrestricted traffic + rationale: Wildcard rules negate the purpose of NSGs and allow any traffic through, creating an open network. + warning_message: NSG rule uses wildcard (*) for source or destination — use specific IP ranges, CIDR blocks, or service + tags. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/networkSecurityGroups + search_patterns: + - sourceAddressPrefix = "*" + - destinationAddressPrefix = "*" + - source_address_prefix = "*" + - destination_address_prefix = "*" + safe_patterns: + - DenyAllInbound + - DenyAllOutbound + - priority = 4096 + correct_patterns: + - sourceAddressPrefix = "10.0.0.0/22" + - sourceAddressPrefix = "VirtualNetwork" + - '# Use CIDR blocks or service tags instead of wildcards' diff --git a/azext_prototype/governance/anti_patterns/security.yaml b/azext_prototype/governance/anti_patterns/security.yaml index 468ff38..67ab0e8 100644 --- a/azext_prototype/governance/anti_patterns/security.yaml +++ b/azext_prototype/governance/anti_patterns/security.yaml @@ -1,76 +1,183 @@ -# Anti-pattern detection — Security domain -# -# Detects credentials, secrets, and insecure configurations in -# AI-generated output. Each pattern entry is evaluated independently; -# when any search_pattern matches and no safe_pattern matches, the -# warning_message is surfaced to the user for review. - -domain: security -description: Credentials, secrets, and insecure configuration detection - -patterns: - - search_patterns: - - "connection_string" - - "connectionstring" - - "access_key" - - "accesskey" - - "account_key" - - "accountkey" - - "shared_access_key" - - "client_secret" - - "password =" - - "password=\"" - - "password='" - safe_patterns: - - "applicationinsights_connection_string" - - "appinsights_connection_string" - - "application_insights_connection_string" - - "appinsights_connectionstring" - warning_message: "Possible credential/secret in output — use managed identity instead of connection strings or keys." - - - search_patterns: - - "admin_enabled = true" - - "admin_username" - - "admin_password" - safe_patterns: [] - warning_message: "Admin credentials detected — use managed identity or RBAC-based authentication instead." - - - search_patterns: - - "hardcoded" - - "hard-coded" - - "hard coded" - safe_patterns: - - "do not hardcode" - - "avoid hardcod" - - "never hardcode" - - "don't hardcode" - warning_message: "Possible hard-coded value detected — externalize secrets to Key Vault or use managed identity." - - - search_patterns: - - "disable_tde" - - "transparent_data_encryption = false" - - "encryption_at_rest = false" - safe_patterns: [] - warning_message: "Encryption at rest appears disabled — leave default encryption enabled on all data services." - - - search_patterns: - - "output \"cosmos_account_primary_key\"" - - "output \"cosmos_primary_key\"" - - "output \"cosmos_connection_strings\"" - - "output \"primary_key\"" - - "output \"primary_connection_string\"" - - "output \"secondary_key\"" - - "output \"storage_account_key\"" - - "output \"storage_primary_key\"" - - "output \"sql_admin_password\"" - safe_patterns: - - "deprecated" - - "do not use" - warning_message: "Sensitive value exposed as Terraform output — remove this output entirely. Use managed identity instead of keys." - - - search_patterns: - - "DO NOT USE - use managed identity" - - "DEPRECATED: Use managed identity" - - "WARNING: Do not use" - safe_patterns: [] - warning_message: "Output marked as 'do not use' should be removed entirely, not left with a warning. Omit sensitive outputs." +kind: anti-pattern +domain: security +description: Credentials, secrets, and insecure configuration detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-SEC-001 + description: Detects connection strings, access keys, or shared secrets that should use managed identity + rationale: Connection strings and access keys are shared secrets that cannot be scoped to specific identities, automatically + rotated, or audited through Entra ID. + warning_message: Possible credential/secret in output — use managed identity instead of connection strings or keys. + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: [] + search_patterns: + - connection_string + - connectionstring + - access_key + - accesskey + - account_key + - accountkey + - shared_access_key + - client_secret + - password = + - password=" + - password=' + safe_patterns: + - applicationinsights_connection_string + - appinsights_connection_string + - application_insights_connection_string + - .properties.connectionstring + - never output + - are disabled + - is disabled + - do not output + - do not use + - prohibited + - defaultazurecredential + correct_patterns: + - '# Use managed identity via DefaultAzureCredential' + - Microsoft.ManagedIdentity/userAssignedIdentities +- id: ANTI-SEC-002 + description: Detects container registry admin credentials enabled instead of managed identity with AcrPull + rationale: Admin credentials are shared secrets that cannot be scoped per-service and bypass RBAC audit trails. + warning_message: Admin credentials detected — disable admin user and use managed identity with AcrPull role assignment. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ContainerRegistry/registries + search_patterns: + - admin_enabled = true + - admin_username + - admin_password + - adminUserEnabled = true + correct_patterns: + - admin_enabled = false + - adminUserEnabled = false + - '# Use managed identity with AcrPull role assignment' +- id: ANTI-SEC-003 + description: Detects hardcoded secret values that should be parameterized or stored in Key Vault + rationale: Hardcoded values in code cannot be rotated and are permanently exposed in source control history. + warning_message: Possible hardcoded value detected — externalize to Key Vault or use variables. + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: [] + search_patterns: + - hardcoded + - hard-coded + - hard coded + safe_patterns: + - do not hardcode + - avoid hardcod + - never hardcode + - don't hardcode + - possible hard-coded value detected + - rather than hardcoded + - instead of hardcod + correct_patterns: + - '# Externalize secrets to Key Vault or use managed identity' +- id: ANTI-SEC-004 + description: Detects disabled encryption at rest on storage or database services + rationale: Disabled encryption exposes data if storage media is compromised or improperly decommissioned. + warning_message: Encryption at rest is disabled — enable TDE for SQL, SSE for Storage. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers + - Microsoft.Sql/servers/databases + search_patterns: + - disable_tde + - transparent_data_encryption = false + correct_patterns: + - transparent_data_encryption = true + - transparentDataEncryption = "Enabled" + - services: + - Microsoft.Storage/storageAccounts + - Microsoft.DocumentDB/databaseAccounts + search_patterns: + - encryption_at_rest = false + correct_patterns: + - encryption_at_rest = true +- id: ANTI-SEC-005 + description: Detects sensitive values exposed as Terraform outputs (keys, passwords, connection strings) + rationale: Terraform outputs are stored in plaintext state files — sensitive values are visible to anyone with state access. + warning_message: Sensitive value in Terraform output — remove the output or add sensitive = true. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - output "cosmos_account_primary_key" + - output "cosmos_primary_key" + - output "cosmos_connection_strings" + - output "primary_key" + - output "primary_connection_string" + - output "secondary_key" + - output "storage_account_key" + - output "storage_primary_key" + - output "sql_admin_password" + safe_patterns: + - deprecated + - do not use + correct_patterns: + - '# Remove sensitive outputs — use managed identity for service-to-service auth' + - output "resource_id" + - output "principal_id" +- id: ANTI-SEC-006 + description: Detects deprecated sensitive outputs with warning comments still present in code + rationale: Outputs marked with "DO NOT USE" or "DEPRECATED" should be removed entirely, not left with warnings. + warning_message: Deprecated sensitive output detected — remove the output entirely instead of adding a warning comment. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - DO NOT USE - use managed identity + - 'DEPRECATED: Use managed identity' + - 'WARNING: Do not use' + correct_patterns: + - '# Remove this output entirely — do not emit sensitive values' +- id: ANTI-SEC-007 + description: Detects Owner or Contributor role assignments on service identities (overprivileged) + rationale: Owner and Contributor roles grant full control — service identities should use the most specific data-plane role + at the narrowest scope. + warning_message: Overprivileged role assignment detected — use the most specific built-in role at the narrowest scope. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Authorization/roleAssignments + search_patterns: + - '"Owner"' + - '"Contributor"' + safe_patterns: + - storage blob data + - key vault secrets + - key vault crypto + - cosmos db + - signalr service owner + - service bus data + - redis cache contributor + - acrpull + - acrpush + - monitoring reader + - log analytics reader + correct_patterns: + - '"Storage Blob Data Contributor"' + - '"Key Vault Secrets User"' + - '# Use the most specific built-in role at the narrowest scope' diff --git a/azext_prototype/governance/anti_patterns/storage.yaml b/azext_prototype/governance/anti_patterns/storage.yaml index a406b59..649a4f8 100644 --- a/azext_prototype/governance/anti_patterns/storage.yaml +++ b/azext_prototype/governance/anti_patterns/storage.yaml @@ -1,24 +1,45 @@ -# Anti-pattern detection — Storage domain -# -# Detects insecure storage and data service configurations in -# AI-generated output. - -domain: storage -description: Storage account, Cosmos DB, and data service configuration detection - -patterns: - - search_patterns: - - "account-level keys" - - "account_key_enabled" - - "shared_key_access = true" - safe_patterns: - - "do not use account-level keys" - - "disable shared key" - warning_message: "Account-level key access detected — use Microsoft Entra RBAC with managed identity instead." - - - search_patterns: - - "allow_blob_public_access = true" - - "public_access = \"blob\"" - - "public_access = \"container\"" - safe_patterns: [] - warning_message: "Public blob access enabled — disable public access and use SAS tokens or managed identity." +kind: anti-pattern +domain: storage +description: Storage account access and data exposure detection +last_updated: '2026-04-04' +patterns: +- id: ANTI-STOR-001 + description: Detects shared key access enabled on storage accounts instead of Entra ID RBAC + rationale: Shared key authentication is a legacy pattern that bypasses Entra ID conditional access, PIM, and per-identity + audit trails. + warning_message: Storage account shared key access enabled — disable shared key and use Entra ID RBAC with managed identity. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + search_patterns: + - account-level keys + - account_key_enabled + - shared_key_access = true + safe_patterns: + - do not use account-level keys + - disable shared key + correct_patterns: + - shared_access_key_enabled = false + - allowSharedKeyAccess = false + - '# Use Microsoft Entra RBAC with managed identity' +- id: ANTI-STOR-002 + description: Detects blob public access enabled on storage containers + rationale: Public blob access allows anonymous internet users to read container contents without any authentication. + warning_message: Blob public access enabled — set allowBlobPublicAccess = false. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + search_patterns: + - allow_blob_public_access = true + - public_access = "blob" + - public_access = "container" + correct_patterns: + - allow_blob_public_access = false + - allowBlobPublicAccess = false + - public_access = "none" diff --git a/azext_prototype/governance/anti_patterns/terraform_structure.yaml b/azext_prototype/governance/anti_patterns/terraform_structure.yaml new file mode 100644 index 0000000..a81d8c9 --- /dev/null +++ b/azext_prototype/governance/anti_patterns/terraform_structure.yaml @@ -0,0 +1,158 @@ +kind: anti-pattern +domain: terraform_structure +description: Provider hygiene, version consistency, tag placement, and azapi conventions +last_updated: '2026-04-04' +patterns: +- id: ANTI-TFS-001 + description: Detects azurerm provider usage — this project uses only the azapi provider + rationale: The azurerm provider is not used in this project. All resources use azapi_resource with ARM resource types. + warning_message: azurerm provider detected — use hashicorp/azapi provider with azapi_resource for all resources. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - source = "hashicorp/azurerm" + - source = "hashicorp/azurerm" + - provider "azurerm" + safe_patterns: + - '# do not use azurerm' + - '# never use azurerm' + - never declare the azurerm + correct_patterns: + - source = "hashicorp/azapi" +- id: ANTI-TFS-002 + description: Detects azurerm_* resource types which require the azurerm provider + rationale: azurerm_* resources require the azurerm provider which is not used; use azapi_resource with ARM resource types + instead. + warning_message: azurerm resource detected — use azapi_resource with the ARM resource type instead. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - azurerm_role_assignment + - azurerm_monitor_metric_alert + - azurerm_storage_management_policy + - azurerm_key_vault_secret + - azurerm_monitor_diagnostic_setting + safe_patterns: + - '# do not use azurerm' + - never use azurerm + correct_patterns: + - Microsoft.Authorization/roleAssignments@ + - Microsoft.Insights/diagnosticSettings@ +- id: ANTI-TFS-003 + description: Detects random provider usage which introduces non-deterministic behavior + rationale: The random provider generates different values on each apply, breaking plan reproducibility and causing unnecessary + resource recreation. + warning_message: Random provider detected — use deterministic alternatives like substr(md5(...)). + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - source = "hashicorp/random" + - source = "hashicorp/random" + - provider "random" + - random_string + - random_id + - random_pet + safe_patterns: + - '# do not use random' + correct_patterns: + - substr(md5("deterministic-seed"), 0, 8) +- id: ANTI-TFS-004 + description: Detects outdated azapi provider version (1.x) — this project requires azapi 2.x + rationale: azapi 1.x uses different output access patterns (jsondecode) and lacks v2 features like direct property access. + warning_message: Outdated azapi provider version detected — use ~> 2.x. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - ~> 1.15 + - ~> 1.14 + - ~> 1.13 + - ~> 1.12 + - ~> 1.11 + - ~> 1.10 + correct_patterns: + - ~> 2.8 + - ~> 2. +- id: ANTI-TFS-005 + description: Detects uuid() function which is non-deterministic and breaks plan reproducibility + rationale: uuid() generates a new value every time Terraform evaluates it, causing unnecessary resource recreation on every + apply. + warning_message: uuid() detected — use uuidv5() with a deterministic seed for reproducible GUIDs. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - uuid() + safe_patterns: + - uuidv5 + - '# never use uuid' + - do not use uuid + correct_patterns: + - uuidv5("6ba7b811-9dad-11d1-80b4-00c04fd430c8", "deterministic-seed") +- id: ANTI-TFS-006 + description: Detects jsondecode() on azapi v2 resource output — use .output.properties.* directly + rationale: azapi v2 provides direct property access via .output.properties.* — jsondecode is a v1 workaround that is unnecessary + and error-prone. + warning_message: jsondecode() on azapi resource output — use .output.properties.* directly (azapi v2 syntax). + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - jsondecode(azapi_resource. + - jsondecode( azapi_resource. + safe_patterns: + - '# jsondecode is for v1.x' + correct_patterns: + - .output.properties. +- id: ANTI-TFS-007 + description: Detects .output.properties.* access without response_export_values on the azapi_resource + rationale: azapi_resource requires response_export_values to be set for any .output.properties.* access — without it, the + value is null. + warning_message: Accessing .output.properties.* without response_export_values — add response_export_values = ["*"] to the + resource. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - .output.properties. + safe_patterns: + - response_export_values + correct_patterns: + - response_export_values = ["*"] +- id: ANTI-TFS-008 + description: Detects data.azurerm_client_config which requires the azurerm provider + rationale: data.azurerm_client_config requires azurerm provider — use var.subscription_id and var.tenant_id instead. + warning_message: data.azurerm_client_config detected — use var.subscription_id and var.tenant_id instead. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - data.azurerm_client_config + - data "azurerm_client_config" + correct_patterns: + - var.subscription_id + - var.tenant_id +- id: ANTI-TFS-009 + description: Detects data.azurerm_subscription which requires the azurerm provider + rationale: data.azurerm_subscription requires azurerm provider — use var.subscription_id for subscription-level references. + warning_message: data.azurerm_subscription detected — use var.subscription_id instead. + applies_to: + - terraform-agent + targets: + - services: [] + search_patterns: + - data.azurerm_subscription + - data "azurerm_subscription" + correct_patterns: + - var.subscription_id diff --git a/azext_prototype/governance/anti_patterns/validate.py b/azext_prototype/governance/anti_patterns/validate.py index 8b4e15e..67ccb97 100644 --- a/azext_prototype/governance/anti_patterns/validate.py +++ b/azext_prototype/governance/anti_patterns/validate.py @@ -1,271 +1,147 @@ -#!/usr/bin/env python -"""Validate anti-pattern YAML files against the expected schema. - -Usage: - # Validate all built-in anti-pattern files - python -m azext_prototype.governance.anti_patterns.validate - - # Validate specific files - python -m azext_prototype.governance.anti_patterns.validate path/to/file.yaml ... - - # Validate a directory - python -m azext_prototype.governance.anti_patterns.validate --dir azext_prototype/governance/anti_patterns/ - - # Strict mode — warnings are treated as errors - python -m azext_prototype.governance.anti_patterns.validate --strict - - # As a pre-commit hook (validates staged anti-pattern YAML files) - python -m azext_prototype.governance.anti_patterns.validate --hook - -Exit codes: - 0 — all files valid - 1 — validation errors found -""" - -from __future__ import annotations - -import argparse -import subprocess -import sys -from dataclasses import dataclass -from pathlib import Path - -import yaml - -# ------------------------------------------------------------------ # -# Validation error -# ------------------------------------------------------------------ # - - -@dataclass -class ValidationError: - """A single validation issue found in an anti-pattern file.""" - - file: str - message: str - severity: str = "error" # error | warning - - def __str__(self) -> str: - return f"[{self.severity.upper()}] {self.file}: {self.message}" - - -# ------------------------------------------------------------------ # -# Schema validation -# ------------------------------------------------------------------ # - -_ANTI_PATTERNS_DIR = Path(__file__).resolve().parent - - -def validate_anti_pattern_file(path: Path) -> list[ValidationError]: - """Validate a single anti-pattern YAML file against the schema. - - Returns a list of validation errors (empty means valid). - """ - errors: list[ValidationError] = [] - filename = str(path) - - # ---- Parse YAML ---- - try: - data = yaml.safe_load(path.read_text(encoding="utf-8")) or {} - except yaml.YAMLError as exc: - errors.append(ValidationError(filename, f"Invalid YAML: {exc}")) - return errors - except OSError as exc: - errors.append(ValidationError(filename, f"Cannot read file: {exc}")) - return errors - - if not isinstance(data, dict): - errors.append(ValidationError(filename, "Root element must be a mapping")) - return errors - - # ---- domain (required) ---- - if "domain" not in data: - errors.append(ValidationError(filename, "Missing required key: 'domain'")) - elif not isinstance(data["domain"], str): - errors.append(ValidationError(filename, "'domain' must be a string")) - - # ---- description (recommended) ---- - if "description" not in data: - errors.append( - ValidationError(filename, "Missing 'description' — recommended for documentation", severity="warning") - ) - - # ---- patterns (required) ---- - patterns = data.get("patterns") - if patterns is None: - errors.append(ValidationError(filename, "Missing required key: 'patterns'")) - return errors - - if not isinstance(patterns, list): - errors.append(ValidationError(filename, "'patterns' must be a list")) - return errors - - if len(patterns) == 0: - errors.append( - ValidationError(filename, "'patterns' is empty — file has no detection rules", severity="warning") - ) - - for i, entry in enumerate(patterns): - prefix = f"patterns[{i}]" - if not isinstance(entry, dict): - errors.append(ValidationError(filename, f"{prefix}: must be a mapping")) - continue - - # search_patterns — required, non-empty list of strings - search = entry.get("search_patterns") - if search is None: - errors.append(ValidationError(filename, f"{prefix} missing required key: 'search_patterns'")) - elif not isinstance(search, list): - errors.append(ValidationError(filename, f"{prefix}.search_patterns must be a list")) - elif len(search) == 0: - errors.append(ValidationError(filename, f"{prefix}.search_patterns is empty")) - else: - for j, s in enumerate(search): - if not isinstance(s, str): - errors.append(ValidationError(filename, f"{prefix}.search_patterns[{j}] must be a string")) - - # safe_patterns — optional, must be list of strings if present - safe = entry.get("safe_patterns") - if safe is not None: - if not isinstance(safe, list): - errors.append(ValidationError(filename, f"{prefix}.safe_patterns must be a list")) - else: - for j, s in enumerate(safe): - if not isinstance(s, str): - errors.append(ValidationError(filename, f"{prefix}.safe_patterns[{j}] must be a string")) - - # warning_message — required, non-empty string - msg = entry.get("warning_message") - if msg is None: - errors.append(ValidationError(filename, f"{prefix} missing required key: 'warning_message'")) - elif not isinstance(msg, str): - errors.append(ValidationError(filename, f"{prefix}.warning_message must be a string")) - elif not msg.strip(): - errors.append(ValidationError(filename, f"{prefix}.warning_message is empty")) - - return errors - - -def validate_anti_pattern_directory(directory: Path) -> list[ValidationError]: - """Validate all YAML files under a directory. - - Returns a combined list of validation errors across all files. - """ - all_errors: list[ValidationError] = [] - if not directory.is_dir(): - return all_errors - - for yaml_file in sorted(directory.glob("*.yaml")): - all_errors.extend(validate_anti_pattern_file(yaml_file)) - - return all_errors - - -# ------------------------------------------------------------------ # -# CLI -# ------------------------------------------------------------------ # - - -def _get_staged_anti_pattern_files() -> list[Path]: - """Return staged anti-pattern YAML files from the git index.""" - try: - result = subprocess.run( - ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"], - capture_output=True, - text=True, - check=True, - ) - except (subprocess.CalledProcessError, FileNotFoundError): - return [] - - return [ - Path(f) - for f in result.stdout.strip().splitlines() - if f.endswith(".yaml") and "anti_patterns" in f and "validate" not in f - ] - - -def main(argv: list[str] | None = None) -> int: - """Entry point for the anti-pattern validator.""" - parser = argparse.ArgumentParser(description="Validate anti-pattern YAML files against the expected schema.") - parser.add_argument( - "files", - nargs="*", - help="Specific YAML files to validate.", - ) - parser.add_argument( - "--dir", - type=str, - default=None, - help="Validate all YAML files under this directory.", - ) - parser.add_argument( - "--strict", - action="store_true", - help="Treat warnings as errors.", - ) - parser.add_argument( - "--hook", - action="store_true", - help="Pre-commit hook mode: validate staged anti-pattern YAML files.", - ) - - args = parser.parse_args(argv) - - errors: list[ValidationError] = [] - - if args.hook: - staged = _get_staged_anti_pattern_files() - if not staged: - return 0 - sys.stdout.write(f"Validating {len(staged)} staged anti-pattern file(s)...\n") - for path in staged: - errors.extend(validate_anti_pattern_file(path)) - - elif args.dir: - directory = Path(args.dir) - if not directory.is_dir(): - sys.stderr.write(f"Error: '{args.dir}' is not a directory\n") - return 1 - yaml_files = sorted(directory.glob("*.yaml")) - sys.stdout.write(f"Validating {len(yaml_files)} anti-pattern file(s) in {args.dir}...\n") - errors.extend(validate_anti_pattern_directory(directory)) - - elif args.files: - sys.stdout.write(f"Validating {len(args.files)} anti-pattern file(s)...\n") - for filepath in args.files: - path = Path(filepath) - if not path.exists(): - sys.stderr.write(f"Error: '{filepath}' does not exist\n") - return 1 - errors.extend(validate_anti_pattern_file(path)) - - else: - # Default: validate built-in anti-patterns - yaml_files = sorted(_ANTI_PATTERNS_DIR.glob("*.yaml")) - sys.stdout.write(f"Validating {len(yaml_files)} built-in anti-pattern file(s)...\n") - errors.extend(validate_anti_pattern_directory(_ANTI_PATTERNS_DIR)) - - # Report results - if not errors: - sys.stdout.write("All anti-pattern files are valid.\n") - return 0 - - actual_errors = [e for e in errors if e.severity == "error"] - warnings = [e for e in errors if e.severity == "warning"] - - for err in errors: - sys.stdout.write(f"{err}\n") - - sys.stdout.write(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)\n") - - if actual_errors: - return 1 - if args.strict and warnings: - return 1 - - return 0 - - -if __name__ == "__main__": - sys.exit(main()) +#!/usr/bin/env python +"""Validate anti-pattern YAML files against the unified schema. + +Usage: + python -m azext_prototype.governance.anti_patterns.validate + python -m azext_prototype.governance.anti_patterns.validate --strict + python -m azext_prototype.governance.anti_patterns.validate --dir path/to/dir + +Exit codes: + 0 — all files valid + 1 — validation errors found +""" + +from __future__ import annotations + +import argparse +import sys +from dataclasses import dataclass +from pathlib import Path + +import yaml + +_AP_DIR = Path(__file__).resolve().parent + +_REQUIRED_TOP_KEYS = {"kind", "domain", "description", "last_updated", "patterns"} + + +@dataclass +class ValidationError: + """A single validation issue found in an anti-pattern file.""" + + file: str + message: str + severity: str = "error" + + def __str__(self) -> str: + return f"[{self.severity.upper()}] {self.file}: {self.message}" + + +def validate_anti_pattern_file(path: Path) -> list[ValidationError]: + """Validate a single anti-pattern YAML file.""" + errors: list[ValidationError] = [] + filename = str(path) + + try: + data = yaml.safe_load(path.read_text(encoding="utf-8")) or {} + except yaml.YAMLError as exc: + errors.append(ValidationError(filename, f"Invalid YAML: {exc}")) + return errors + except OSError as exc: + errors.append(ValidationError(filename, f"Cannot read file: {exc}")) + return errors + + if not isinstance(data, dict): + errors.append(ValidationError(filename, "Root element must be a mapping")) + return errors + + for key in _REQUIRED_TOP_KEYS: + if key not in data: + errors.append(ValidationError(filename, f"Missing required key: '{key}'")) + + if data.get("kind") != "anti-pattern": + errors.append(ValidationError(filename, f"kind must be 'anti-pattern', got '{data.get('kind')}'")) + + patterns = data.get("patterns", []) + if not isinstance(patterns, list): + errors.append(ValidationError(filename, "'patterns' must be a list")) + return errors + + pattern_ids: set[str] = set() + for i, entry in enumerate(patterns): + prefix = f"patterns[{i}]" + if not isinstance(entry, dict): + errors.append(ValidationError(filename, f"{prefix}: must be a mapping")) + continue + + pid = entry.get("id", "") + if not pid: + errors.append(ValidationError(filename, f"{prefix}: missing 'id'")) + elif pid in pattern_ids: + errors.append(ValidationError(filename, f"{prefix}: duplicate id '{pid}'")) + else: + pattern_ids.add(pid) + + if not entry.get("description"): + errors.append(ValidationError(filename, f"{prefix} ({pid}): missing 'description'")) + + if not entry.get("warning_message"): + errors.append(ValidationError(filename, f"{prefix} ({pid}): missing 'warning_message'")) + + targets = entry.get("targets") + if not isinstance(targets, dict): + errors.append(ValidationError(filename, f"{prefix} ({pid}): missing or invalid 'targets'")) + elif not targets.get("search_patterns"): + errors.append(ValidationError(filename, f"{prefix} ({pid}): missing 'targets.search_patterns'")) + + applies_to = entry.get("applies_to") + if applies_to is not None and not isinstance(applies_to, list): + errors.append(ValidationError(filename, f"{prefix} ({pid}): 'applies_to' must be a list")) + + return errors + + +def validate_anti_pattern_directory(directory: Path) -> list[ValidationError]: + """Validate all anti-pattern YAML files in a directory.""" + all_errors: list[ValidationError] = [] + if not directory.is_dir(): + return all_errors + for f in sorted(directory.glob("*.yaml")): + all_errors.extend(validate_anti_pattern_file(f)) + return all_errors + + +def main(argv: list[str] | None = None) -> int: + """CLI entry point.""" + parser = argparse.ArgumentParser(description="Validate anti-pattern YAML files.") + parser.add_argument("files", nargs="*", help="Specific files to validate") + parser.add_argument("--dir", type=str, help="Directory to validate") + parser.add_argument("--strict", action="store_true", help="Treat warnings as errors") + args = parser.parse_args(argv) + + if args.dir: + errors = validate_anti_pattern_directory(Path(args.dir)) + elif args.files: + errors = [] + for f in args.files: + errors.extend(validate_anti_pattern_file(Path(f))) + else: + errors = validate_anti_pattern_directory(_AP_DIR) + + if not errors: + print("All anti-pattern files valid.") + return 0 + + for e in errors: + print(e) + + actual = [e for e in errors if e.severity == "error"] + warnings = [e for e in errors if e.severity == "warning"] + + if actual or (args.strict and warnings): + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/azext_prototype/governance/embeddings.py b/azext_prototype/governance/embeddings.py new file mode 100644 index 0000000..49a728a --- /dev/null +++ b/azext_prototype/governance/embeddings.py @@ -0,0 +1,179 @@ +"""Embedding backends for policy retrieval. + +Provides pluggable backends for converting policy rule text into +vectors for similarity search. + +- **TFIDFBackend**: Pure-Python TF-IDF. Zero dependencies, near-instant + for small corpora. Default backend (always available). +- **NeuralBackend**: Uses ``sentence-transformers`` (optional). + Auto-detected when installed. Requires ``torch`` which is unavailable + on Azure CLI's 32-bit Windows Python. Install manually: + ``pip install sentence-transformers``. +""" + +from __future__ import annotations + +import logging +import math +from abc import ABC, abstractmethod +from collections import Counter +from typing import Any + +logger = logging.getLogger(__name__) + + +class EmbeddingBackend(ABC): + """Abstract interface for embedding text into vectors.""" + + @abstractmethod + def embed(self, texts: list[str]) -> list[list[float]]: + """Embed a batch of texts into vectors.""" + + @abstractmethod + def embed_query(self, text: str) -> list[float]: + """Embed a single query text.""" + + +# ------------------------------------------------------------------ # +# TF-IDF backend — pure Python, always available +# ------------------------------------------------------------------ # + + +class TFIDFBackend(EmbeddingBackend): + """TF-IDF embedding backend using pure Python. + + Suitable for small corpora (<1000 documents). For policy rules + (~60 items), vectorization and retrieval are near-instant. + """ + + def __init__(self) -> None: + self._vocab: dict[str, int] = {} + self._idf: dict[str, float] = {} + self._fitted = False + + def fit(self, corpus: list[str]) -> None: + """Build vocabulary and IDF weights from a corpus.""" + # Build vocabulary + vocab_set: set[str] = set() + doc_freq: Counter[str] = Counter() + for doc in corpus: + tokens = set(self._tokenize(doc)) + vocab_set.update(tokens) + for token in tokens: + doc_freq[token] += 1 + + self._vocab = {word: idx for idx, word in enumerate(sorted(vocab_set))} + n = len(corpus) + self._idf = {word: math.log((n + 1) / (freq + 1)) + 1 for word, freq in doc_freq.items()} + self._fitted = True + + def embed(self, texts: list[str]) -> list[list[float]]: + """Embed texts using TF-IDF vectors. Calls ``fit()`` if needed.""" + if not self._fitted: + self.fit(texts) + return [self._vectorize(text) for text in texts] + + def embed_query(self, text: str) -> list[float]: + """Embed a single query.""" + if not self._fitted: + raise RuntimeError("TFIDFBackend must be fit() before embed_query()") + return self._vectorize(text) + + def _tokenize(self, text: str) -> list[str]: + """Simple whitespace + lowercase tokenizer.""" + return [w.strip(".,;:!?()[]{}\"'").lower() for w in text.split() if len(w) > 1] + + def _vectorize(self, text: str) -> list[float]: + """Convert text to a TF-IDF vector.""" + tokens = self._tokenize(text) + tf = Counter(tokens) + vec = [0.0] * len(self._vocab) + for token, count in tf.items(): + if token in self._vocab: + idx = self._vocab[token] + vec[idx] = count * self._idf.get(token, 0.0) + # L2 normalize + norm = math.sqrt(sum(v * v for v in vec)) + if norm > 0: + vec = [v / norm for v in vec] + return vec + + +# ------------------------------------------------------------------ # +# Neural backend — sentence-transformers +# ------------------------------------------------------------------ # + +_neural_model: Any = None + + +class NeuralBackend(EmbeddingBackend): + """Sentence-transformers embedding backend. + + Uses ``all-MiniLM-L6-v2`` (~80MB) for fast, high-quality embeddings. + The model is loaded once and cached for the session. + """ + + MODEL_NAME = "all-MiniLM-L6-v2" + + def __init__(self, status_fn: Any = None) -> None: + self._status_fn = status_fn + self._model = self._get_or_load_model() + + def _get_or_load_model(self) -> Any: + """Load model (cached across instances within a session).""" + global _neural_model + if _neural_model is not None: + return _neural_model + + from sentence_transformers import SentenceTransformer + + logger.info("Loading embedding model %s...", self.MODEL_NAME) + _neural_model = SentenceTransformer(self.MODEL_NAME) + return _neural_model + + def embed(self, texts: list[str]) -> list[list[float]]: + """Embed texts using the neural model.""" + embeddings = self._model.encode(texts, show_progress_bar=False, convert_to_numpy=True) + return [e.tolist() for e in embeddings] + + def embed_query(self, text: str) -> list[float]: + """Embed a single query.""" + embedding = self._model.encode([text], show_progress_bar=False, convert_to_numpy=True) + return embedding[0].tolist() + + +# ------------------------------------------------------------------ # +# Similarity +# ------------------------------------------------------------------ # + + +def cosine_similarity(a: list[float], b: list[float]) -> float: + """Compute cosine similarity between two vectors.""" + dot = sum(x * y for x, y in zip(a, b)) + norm_a = math.sqrt(sum(x * x for x in a)) + norm_b = math.sqrt(sum(x * x for x in b)) + if norm_a == 0 or norm_b == 0: + return 0.0 + return dot / (norm_a * norm_b) + + +# ------------------------------------------------------------------ # +# Backend factory +# ------------------------------------------------------------------ # + + +def create_backend(prefer_neural: bool = True, status_fn: Any = None) -> EmbeddingBackend: + """Create the best available embedding backend. + + Defaults to TF-IDF (always available, zero dependencies). + Upgrades to neural (sentence-transformers) when installed and + *prefer_neural* is True. Falls back silently to TF-IDF when + ``sentence-transformers`` or ``torch`` is unavailable (e.g. Azure + CLI 32-bit Windows Python). + """ + if prefer_neural: + try: + return NeuralBackend(status_fn=status_fn) + except Exception as exc: + logger.info("Neural embedding backend unavailable (%s), using TF-IDF", exc) + return TFIDFBackend() diff --git a/azext_prototype/governance/governance_index.py b/azext_prototype/governance/governance_index.py new file mode 100644 index 0000000..54c9112 --- /dev/null +++ b/azext_prototype/governance/governance_index.py @@ -0,0 +1,349 @@ +"""Governance index — embedding-based retrieval of policies, anti-patterns, standards, and transforms. + +Pre-processes governance items (rules, patterns, principles, transforms) into vectors +for fast semantic retrieval. Supports pre-computed embeddings shipped with +the wheel as well as runtime computation and disk caching. + +Vector files are stored in ``governance/`` as: +- ``policy.vectors.json`` +- ``anti-pattern.vectors.json`` +- ``standard.vectors.json`` +- ``transform.vectors.json`` +""" + +from __future__ import annotations + +import json +import logging +from dataclasses import asdict, dataclass +from pathlib import Path +from typing import Any + +from azext_prototype.governance.embeddings import ( + EmbeddingBackend, + cosine_similarity, + create_backend, +) + +logger = logging.getLogger(__name__) + +CACHE_FILE = ".prototype/governance/governance_embeddings.json" + +# Pre-computed vector filenames (shipped with the wheel) +_VECTOR_FILES = { + "policy": "policy.vectors.json", + "anti-pattern": "anti-pattern.vectors.json", + "standard": "standard.vectors.json", + "transform": "transform.vectors.json", +} + + +@dataclass +class IndexedItem: + """A single governance item (rule, pattern, or principle) with metadata.""" + + kind: str # "policy" | "anti-pattern" | "standard" + item_id: str + severity: str # "required" | "recommended" | "optional" | "" (standards) + description: str + rationale: str + source_name: str # policy name, anti-pattern domain, standard domain + domain: str + services: list[str] # ARM namespaces + applies_to: list[str] # agent names + + @property + def text_for_embedding(self) -> str: + """Combine fields into a single text for embedding.""" + parts = [ + f"[{self.kind}:{self.domain}] {self.source_name}", + f"{self.item_id}: {self.description}", + ] + if self.severity: + parts[1] = f"{self.item_id} ({self.severity}): {self.description}" + if self.rationale: + parts.append(f"Rationale: {self.rationale}") + if self.services: + parts.append(f"Services: {', '.join(self.services)}") + return " ".join(parts) + + +class GovernanceIndex: + """Indexed governance items for fast semantic retrieval. + + Build once from the loaded policies, anti-patterns, and standards, + then ``retrieve()`` to find the top-k most relevant items for a task. + """ + + def __init__(self, backend: EmbeddingBackend | None = None) -> None: + self._backend = backend or create_backend() + self._items: list[IndexedItem] = [] + self._vectors: list[list[float]] = [] + self._built = False + + @property + def rule_count(self) -> int: + """Total number of indexed items (backward compat name).""" + return len(self._items) + + def load_precomputed(self) -> bool: + """Load pre-computed embeddings shipped with the package. + + Reads all three vector files (policy, anti-pattern, standard) from + the ``governance/`` directory and merges them into a single index. + Falls back gracefully if any file is missing. + """ + governance_dir = Path(__file__).parent + loaded_any = False + + for kind, filename in _VECTOR_FILES.items(): + vectors_path = governance_dir / filename + if not vectors_path.exists(): + continue + try: + data = json.loads(vectors_path.read_text(encoding="utf-8")) + for r in data.get("rules", data.get("items", [])): + self._items.append( + IndexedItem( + kind=r.get("kind", kind), + item_id=r.get("item_id", r.get("rule_id", "")), + severity=r.get("severity", ""), + description=r.get("description", ""), + rationale=r.get("rationale", ""), + source_name=r.get("source_name", r.get("policy_name", "")), + domain=r.get("domain", ""), + services=r.get("services", []), + applies_to=r.get("applies_to", []), + ) + ) + self._vectors.append(r["vector"]) + loaded_any = True + logger.debug("Loaded %s vectors from %s", kind, vectors_path.name) + except (json.JSONDecodeError, KeyError, TypeError) as exc: + logger.warning("Failed to load %s vectors: %s", kind, exc) + + self._built = loaded_any and len(self._items) > 0 + if self._built: + logger.debug("Total governance index: %d items", len(self._items)) + return self._built + + def build(self, policies: list[Any]) -> None: + """Extract items from loaded policies and compute embeddings. + + Parameters + ---------- + policies: + List of ``Policy`` objects from ``PolicyEngine.list_policies()``. + Anti-patterns and standards are loaded internally. + """ + from azext_prototype.debug_log import log_flow + + self._items = [] + + # Index policies + for policy in policies: + policy_domain = getattr(policy, "domain", "") + source_name = getattr(policy, "name", "") + services = getattr(policy, "services", []) + for rule in getattr(policy, "rules", []): + rule_targets = getattr(rule, "targets", []) + rule_services: list[str] = [] + for t in (rule_targets if isinstance(rule_targets, list) else []): + if isinstance(t, dict): + rule_services.extend(t.get("services", [])) + rule_services = rule_services or services + self._items.append( + IndexedItem( + kind="policy", + item_id=getattr(rule, "id", ""), + severity=getattr(rule, "severity", "recommended"), + description=getattr(rule, "description", ""), + rationale=getattr(rule, "rationale", ""), + source_name=source_name, + domain=policy_domain, + services=rule_services, + applies_to=getattr(rule, "applies_to", []), + ) + ) + + # Index anti-patterns + try: + from azext_prototype.governance.anti_patterns import ( + load as load_anti_patterns, + ) + + for check in load_anti_patterns(): + self._items.append( + IndexedItem( + kind="anti-pattern", + item_id=check.id, + severity="", + description=check.description or check.warning_message, + rationale=check.rationale, + source_name=check.domain, + domain=check.domain, + services=[s for t in check.targets if isinstance(t, dict) for s in t.get("services", [])], + applies_to=check.applies_to, + ) + ) + except Exception as exc: + logger.debug("Skipping anti-pattern indexing: %s", exc) + + # Index standards + try: + from azext_prototype.governance.standards import load as load_standards + + for standard in load_standards(): + for principle in standard.principles: + self._items.append( + IndexedItem( + kind="standard", + item_id=principle.id, + severity="", + description=principle.description, + rationale=principle.rationale, + source_name=standard.domain, + domain=standard.domain, + services=[], + applies_to=principle.applies_to, + ) + ) + except Exception as exc: + logger.debug("Skipping standards indexing: %s", exc) + + # Index transforms + try: + from azext_prototype.governance.transforms import load as load_transforms + + for tfm in load_transforms(): + tfm_services: list[str] = [] + for t in tfm.targets: + if isinstance(t, dict): + tfm_services.extend(t.get("services", [])) + self._items.append( + IndexedItem( + kind="transform", + item_id=tfm.id, + severity="", + description=tfm.description, + rationale=tfm.rationale, + source_name=tfm.domain, + domain=tfm.domain, + services=tfm_services, + applies_to=tfm.applies_to, + ) + ) + except Exception as exc: + logger.debug("Skipping transforms indexing: %s", exc) + + if not self._items: + self._built = True + return + + texts = [item.text_for_embedding for item in self._items] + log_flow("GovernanceIndex.build", f"Embedding {len(texts)} governance items") + self._vectors = self._backend.embed(texts) + self._built = True + log_flow( + "GovernanceIndex.build", + f"Index built: {len(self._items)} items, {len(self._vectors[0])}-dim vectors", + ) + + def retrieve( + self, + query: str, + top_k: int = 10, + kind: str | None = None, + services: list[str] | None = None, + ) -> list[IndexedItem]: + """Find the top-k most relevant items for a query. + + Parameters + ---------- + query: + Task description or context to match against. + top_k: + Maximum number of items to return. + kind: + Optional filter — only return items of this kind + ("policy", "anti-pattern", "standard"). + services: + ARM resource type namespaces. When provided, items whose + ``services`` list specific namespaces that don't overlap + are excluded. Items with empty services pass through. + """ + if not self._built or not self._items: + return [] + + svc_set = {s.lower() for s in services} if services else None + + query_vec = self._backend.embed_query(query) + scored = [(cosine_similarity(query_vec, vec), item) for vec, item in zip(self._vectors, self._items)] + scored.sort(key=lambda x: x[0], reverse=True) + + results = [] + for _, item in scored: + if kind and item.kind != kind: + continue + # Filter by service namespace overlap + if svc_set is not None and item.services: + item_svcs = {s.lower() for s in item.services} + if not (item_svcs & svc_set): + continue + results.append(item) + if len(results) >= top_k: + break + return results + + def retrieve_for_agent( + self, + query: str, + agent_name: str, + top_k: int = 10, + kind: str | None = None, + services: list[str] | None = None, + ) -> list[IndexedItem]: + """Retrieve items filtered by agent applicability and service namespace.""" + candidates = self.retrieve(query, top_k=top_k * 2, kind=kind, services=services) + filtered = [] + for item in candidates: + if not item.applies_to or agent_name in item.applies_to: + filtered.append(item) + if len(filtered) >= top_k: + break + return filtered + + # ------------------------------------------------------------------ # + # Cache + # ------------------------------------------------------------------ # + + def save_cache(self, project_dir: str) -> None: + """Persist the index to disk for fast reload.""" + if not self._built: + return + path = Path(project_dir) / CACHE_FILE + path.parent.mkdir(parents=True, exist_ok=True) + data = { + "items": [asdict(item) for item in self._items], + "vectors": self._vectors, + } + with open(path, "w", encoding="utf-8") as f: + json.dump(data, f) + logger.debug("Saved governance index cache to %s", path) + + def load_cache(self, project_dir: str) -> bool: + """Load a previously cached index. Returns True if successful.""" + path = Path(project_dir) / CACHE_FILE + if not path.exists(): + return False + try: + with open(path, "r", encoding="utf-8") as f: + data = json.load(f) + self._items = [IndexedItem(**item) for item in data["items"]] + self._vectors = data["vectors"] + self._built = True + logger.debug("Loaded governance index cache from %s (%d items)", path, len(self._items)) + return True + except (json.JSONDecodeError, KeyError, TypeError) as exc: + logger.warning("Failed to load governance index cache: %s", exc) + return False diff --git a/azext_prototype/governance/governor.py b/azext_prototype/governance/governor.py new file mode 100644 index 0000000..61fd5cc --- /dev/null +++ b/azext_prototype/governance/governor.py @@ -0,0 +1,289 @@ +"""Governor — embedding-based policy retrieval and enforcement. + +Provides three operations: + +1. **retrieve(task)** — Find the most relevant policy rules for a task + using embedding similarity (semantic search). +2. **brief(task)** — Retrieve relevant policies and format as a concise + (<2KB) set of directives for injection into an agent's prompt. +3. **review(output)** — Review generated output against the full policy + set using parallel chunked evaluation. + +The governor replaces the previous approach of injecting ALL policies +(~40KB) into every agent's system prompt. Instead, only the relevant +rules (~1-2KB) are injected, and a thorough post-generation review +catches violations that the brief might not cover. +""" + +from __future__ import annotations + +import logging +from concurrent.futures import ThreadPoolExecutor, as_completed +from typing import Any + +from azext_prototype.governance.embeddings import create_backend +from azext_prototype.governance.governance_index import GovernanceIndex, IndexedItem + +logger = logging.getLogger(__name__) + +# Singleton index — built once per session +_governance_index: GovernanceIndex | None = None + + +def _get_or_build_index(project_dir: str, status_fn: Any = None) -> GovernanceIndex: + """Get or lazily build the governance index.""" + global _governance_index + if _governance_index is not None and _governance_index.rule_count > 0: + return _governance_index + + from azext_prototype.debug_log import log_flow, log_timer + from azext_prototype.governance.policies import PolicyEngine + + # 1. Try pre-computed embeddings shipped with the wheel (no deps, instant) + index = GovernanceIndex(backend=create_backend(prefer_neural=True, status_fn=status_fn)) + if index.load_precomputed(): + log_flow("governor._get_or_build_index", "Loaded pre-computed embeddings", rules=index.rule_count) + _governance_index = index + return index + + # 2. Try project-level cache + if index.load_cache(project_dir): + log_flow("governor._get_or_build_index", "Loaded from project cache", rules=index.rule_count) + _governance_index = index + return index + + # 3. Build from scratch (TF-IDF or neural if available) + with log_timer("governor._get_or_build_index", "Building governance index"): + engine = PolicyEngine() + engine.load() + index.build(engine.list_policies()) + index.save_cache(project_dir) + + log_flow("governor._get_or_build_index", "Built fresh index", rules=index.rule_count) + _governance_index = index + return index + + +def reset_index() -> None: + """Clear the cached index (for tests or after governance changes).""" + global _governance_index + _governance_index = None + + +# ------------------------------------------------------------------ # +# Brief — concise policy directives for agent prompts +# ------------------------------------------------------------------ # + + +def brief( + project_dir: str, + task_description: str, + agent_name: str = "", + top_k: int = 10, + status_fn: Any = None, + services: list[str] | None = None, +) -> str: + """Retrieve relevant policies and format as concise directives. + + This is a **code-level operation** — no AI call is made. The output + is a compact (~1-2KB) set of rules suitable for injection into an + agent's system prompt, replacing the previous ~40KB full policy dump. + + Parameters + ---------- + project_dir: + Project directory (for index cache). + task_description: + Description of the current task (used as the retrieval query). + agent_name: + Name of the agent that will receive the brief. Rules are filtered + by ``applies_to`` if set. + top_k: + Maximum number of rules to include. + status_fn: + Optional status callback for loading indicators. + services: + ARM resource type namespaces for this stage (e.g., + ``["Microsoft.KeyVault/vaults"]``). When provided, rules whose + ``targets.services`` don't overlap are excluded. Rules with + no service targeting pass through. + """ + from azext_prototype.debug_log import log_flow + + index = _get_or_build_index(project_dir, status_fn=status_fn) + if agent_name: + rules = index.retrieve_for_agent(task_description, agent_name, top_k=top_k, services=services) + else: + rules = index.retrieve(task_description, top_k=top_k, services=services) + + # Always include MUST rules with severity="required" regardless of + # embedding similarity — these are universal governance constraints + # (e.g. network isolation, managed identity) that apply to ALL infra stages. + all_rules = index.retrieve(task_description, top_k=top_k * 3, services=services) + must_rules = [r for r in all_rules if r.severity == "required" and r not in rules] + combined = list(rules) + for r in must_rules: + if r.item_id not in {existing.item_id for existing in combined}: + combined.append(r) + + log_flow("governor.brief", f"Retrieved {len(rules)} + {len(combined) - len(rules)} MUST rules", agent=agent_name) + + if not combined: + return "" + + return _format_brief(combined) + + +def _format_brief(rules: list[IndexedItem]) -> str: + """Format a fixed-size governance posture summary. + + Produces a concise summary (~800-1000 chars) regardless of how many + rules were retrieved. Scales to thousands of policies because the + output is a summary with capped directives, not a dump of every rule. + + The anti-pattern scanner remains the enforcement backstop — the + brief's job is to GUIDE, the scanner GUARANTEES compliance. + """ + must_rules = [r for r in rules if r.severity == "required"] + + lines = ["## Governance Posture for This Stage", ""] + lines.append("ALL generated code MUST comply with these requirements:") + lines.append("") + + # Part 1: Top 8 MUST directives (deduplicated, concise) + seen: set[str] = set() + directives: list[str] = [] + for rule in must_rules: + key = rule.description[:50].lower() + if key in seen: + continue + seen.add(key) + directives.append(rule.description) + if len(directives) >= 8: + break + for i, d in enumerate(directives, 1): + lines.append(f"{i}. {d}") + + # Part 2: Correct property values from anti-patterns (deduplicated, max 15) + try: + from azext_prototype.governance import anti_patterns + + ap_checks = anti_patterns.load() + correct: list[str] = [] + for check in ap_checks: + correct.extend(check.correct_patterns) + + # Deduplicate, skip comments, prioritize networking patterns, cap at 15 + seen_cp: set[str] = set() + unique: list[str] = [] + # Networking patterns first (publicNetworkAccess etc.) + net_checks = [c for c in ap_checks if c.domain == "networking"] + other_checks = [c for c in ap_checks if c.domain != "networking"] + for check in net_checks + other_checks: + for cp in check.correct_patterns: + if cp.lower() not in seen_cp and not cp.startswith("#"): + seen_cp.add(cp.lower()) + unique.append(cp) + unique = unique[:15] + + if unique: + lines.append("") + lines.append("## Correct Property Values (use these EXACTLY)") + for cp in unique: + lines.append(f" `{cp}`") + except Exception: + pass + + lines.append("") + lines.append("Code that violates any requirement above will be rejected.") + return "\n".join(lines) + + +# ------------------------------------------------------------------ # +# Review — parallel chunked policy evaluation +# ------------------------------------------------------------------ # + + +def review( + project_dir: str, + output_text: str, + ai_provider: Any, + max_workers: int = 2, + status_fn: Any = None, +) -> list[str]: + """Review generated output against the full policy set. + + Splits policies into batches and evaluates each batch in parallel + using the AI provider. Returns a list of violation descriptions. + + Parameters + ---------- + project_dir: + Project directory (for index cache). + output_text: + The generated code/architecture to review. + ai_provider: + AI provider instance for making review calls. + max_workers: + Maximum concurrent review threads. + status_fn: + Optional status callback. + """ + from azext_prototype.ai.provider import AIMessage + from azext_prototype.debug_log import log_flow + from azext_prototype.governance.policies import PolicyEngine + + engine = PolicyEngine() + engine.load() + policies = engine.list_policies() + + if not policies: + return [] + + # Split into batches of 3-4 policies each + batch_size = 3 + batches = [policies[i : i + batch_size] for i in range(0, len(policies), batch_size)] + log_flow("governor.review", f"Reviewing against {len(policies)} policies in {len(batches)} batches") + + all_violations: list[str] = [] + + def _review_batch(batch: list) -> list[str]: + """Review one batch of policies against the output.""" + policy_text = "\n\n".join(_format_policy_for_review(p) for p in batch) + prompt = ( + "You are a governance reviewer. Review the following generated output " + "against the policy rules below. List ONLY actual violations — do not " + "list rules that are followed correctly. If there are no violations, " + "respond with exactly: [NO_VIOLATIONS]\n\n" + f"## Generated Output\n```\n{output_text[:8000]}\n```\n\n" + f"## Policy Rules\n{policy_text}" + ) + system = AIMessage(role="system", content="You are a strict governance policy reviewer.") + user_msg = AIMessage(role="user", content=prompt) + try: + response = ai_provider.chat([system, user_msg], temperature=0.1, max_tokens=2048) + if "[NO_VIOLATIONS]" in response.content: + return [] + return [line.strip() for line in response.content.strip().splitlines() if line.strip().startswith("-")] + except Exception as exc: + logger.warning("Governor review batch failed: %s", exc) + return [] + + with ThreadPoolExecutor(max_workers=max_workers) as executor: + futures = {executor.submit(_review_batch, batch): i for i, batch in enumerate(batches)} + for future in as_completed(futures): + violations = future.result() + all_violations.extend(violations) + + log_flow("governor.review", f"Review complete: {len(all_violations)} violations found") + return all_violations + + +def _format_policy_for_review(policy: Any) -> str: + """Format a single policy for the review prompt.""" + lines = [f"### {getattr(policy, 'name', 'unknown')} ({getattr(policy, 'domain', '')})"] + for rule in getattr(policy, "rules", []): + severity = getattr(rule, "severity", "recommended") + desc = getattr(rule, "description", "") + lines.append(f"- [{severity.upper()}] {getattr(rule, 'id', '')}: {desc}") + return "\n".join(lines) diff --git a/azext_prototype/governance/policies/__init__.py b/azext_prototype/governance/policies/__init__.py index 71a2aea..d9457ae 100644 --- a/azext_prototype/governance/policies/__init__.py +++ b/azext_prototype/governance/policies/__init__.py @@ -21,23 +21,31 @@ logger = logging.getLogger(__name__) # ------------------------------------------------------------------ # -# Schema constants — keep in sync with the .policy.yaml spec +# Schema constants — keep in sync with governance/schemas/policy.schema.json # ------------------------------------------------------------------ # -SUPPORTED_API_VERSIONS = ("v1",) SUPPORTED_KINDS = ("policy",) VALID_SEVERITIES = ("required", "recommended", "optional") -VALID_CATEGORIES = ("azure", "security", "integration", "cost", "data", "general") -# Required top-level keys that every policy file must contain -_REQUIRED_TOP_KEYS = {"metadata"} -_REQUIRED_METADATA_KEYS = {"name", "category", "services"} -_REQUIRED_RULE_KEYS = {"id", "severity", "description", "applies_to"} +# Required top-level keys (new unified format) +_REQUIRED_TOP_KEYS = {"kind", "domain", "description", "last_updated", "rules"} +_REQUIRED_RULE_KEYS = {"id", "severity", "description"} # ------------------------------------------------------------------ # # Data classes # ------------------------------------------------------------------ # +@dataclass +class CompanionResource: + """A resource that must accompany the primary resource.""" + + type: str + description: str + name: str = "" + terraform_pattern: str = "" + bicep_pattern: str = "" + + @dataclass class PolicyRule: """A single governance rule.""" @@ -46,7 +54,12 @@ class PolicyRule: severity: str # required | recommended | optional description: str rationale: str = "" + warning_message: str = "" applies_to: list[str] = field(default_factory=list) + targets: list = field( + default_factory=list + ) # [{"services": [...], "terraform_pattern": "...", "prohibitions": [...]}] + companion_resources: list[CompanionResource] = field(default_factory=list) @dataclass @@ -63,13 +76,14 @@ class Policy: """A loaded policy document.""" name: str - category: str - services: list[str] = field(default_factory=list) + domain: str + description: str = "" + last_updated: str = "" + services: list[str] = field(default_factory=list) # backward compat aggregate rules: list[PolicyRule] = field(default_factory=list) patterns: list[PolicyPattern] = field(default_factory=list) anti_patterns: list[dict[str, str]] = field(default_factory=list) references: list[dict[str, str]] = field(default_factory=list) - last_reviewed: str = "" # ------------------------------------------------------------------ # @@ -90,7 +104,7 @@ def __str__(self) -> str: def validate_policy_file(path: Path) -> list[ValidationError]: - """Validate a single .policy.yaml file against the schema. + """Validate a single .policy.yaml file against the unified schema. Returns a list of validation errors (empty means valid). """ @@ -111,16 +125,6 @@ def validate_policy_file(path: Path) -> list[ValidationError]: errors.append(ValidationError(filename, "Root element must be a mapping")) return errors - # ---- apiVersion ---- - api_version = data.get("apiVersion") - if api_version and api_version not in SUPPORTED_API_VERSIONS: - errors.append( - ValidationError( - filename, - f"Unsupported apiVersion '{api_version}'. " f"Supported: {', '.join(SUPPORTED_API_VERSIONS)}", - ) - ) - # ---- kind ---- kind = data.get("kind") if kind and kind not in SUPPORTED_KINDS: @@ -131,33 +135,10 @@ def validate_policy_file(path: Path) -> list[ValidationError]: ) ) - # ---- metadata ---- - metadata = data.get("metadata") - if metadata is None: - errors.append(ValidationError(filename, "Missing required key: 'metadata'")) - return errors # can't validate further without metadata - - if not isinstance(metadata, dict): - errors.append(ValidationError(filename, "'metadata' must be a mapping")) - return errors - - for key in _REQUIRED_METADATA_KEYS: - if key not in metadata: - errors.append(ValidationError(filename, f"metadata missing required key: '{key}'")) - - category = metadata.get("category", "") - if category and category not in VALID_CATEGORIES: - errors.append( - ValidationError( - filename, - f"metadata.category '{category}' is not valid. " f"Allowed: {', '.join(VALID_CATEGORIES)}", - severity="warning", - ) - ) - - services = metadata.get("services") - if services is not None and not isinstance(services, list): - errors.append(ValidationError(filename, "metadata.services must be a list")) + # ---- Validate required top-level keys ---- + for key in _REQUIRED_TOP_KEYS: + if key not in data: + errors.append(ValidationError(filename, f"Missing required key: '{key}'")) # ---- rules ---- rules = data.get("rules", []) @@ -165,7 +146,8 @@ def validate_policy_file(path: Path) -> list[ValidationError]: errors.append(ValidationError(filename, "'rules' must be a list")) rules = [] - rule_ids: set[str] = set() + # Same ID is allowed with different targets (different services) + rule_id_targets: set[tuple] = set() for i, rule in enumerate(rules): prefix = f"rules[{i}]" if not isinstance(rule, dict): @@ -177,31 +159,33 @@ def validate_policy_file(path: Path) -> list[ValidationError]: errors.append(ValidationError(filename, f"{prefix} missing required key: '{key}'")) rid = rule.get("id", "") + targets = rule.get("targets", []) + if isinstance(targets, dict): + targets = [targets] + all_svcs = [] + for t in targets if isinstance(targets, list) else []: + all_svcs.extend(t.get("services", []) if isinstance(t, dict) else []) + target_svcs = tuple(sorted(all_svcs)) + key = (rid, target_svcs) if rid: - if rid in rule_ids: - errors.append(ValidationError(filename, f"{prefix}: duplicate rule id '{rid}'")) - rule_ids.add(rid) + if key in rule_id_targets: + errors.append( + ValidationError(filename, f"{prefix}: duplicate rule id+targets '{rid}' for {target_svcs}") + ) + rule_id_targets.add(key) severity = rule.get("severity", "") if severity and severity not in VALID_SEVERITIES: errors.append( ValidationError( filename, - f"{prefix}: invalid severity '{severity}'. " f"Allowed: {', '.join(VALID_SEVERITIES)}", + f"{prefix}: invalid severity '{severity}'. Allowed: {', '.join(VALID_SEVERITIES)}", ) ) applies_to = rule.get("applies_to") if applies_to is not None and not isinstance(applies_to, list): errors.append(ValidationError(filename, f"{prefix}.applies_to must be a list")) - elif isinstance(applies_to, list) and len(applies_to) == 0: - errors.append( - ValidationError( - filename, - f"{prefix}.applies_to is empty — rule will never be resolved", - severity="warning", - ) - ) # ---- patterns (optional) ---- patterns = data.get("patterns", []) @@ -316,7 +300,8 @@ def resolve( for policy in self._policies: # Filter by service if specified if services: - overlap = set(policy.services) & {s.lower() for s in services} + policy_svcs = {s.lower() for s in policy.services} + overlap = policy_svcs & {s.lower() for s in services} if not overlap: continue @@ -332,13 +317,12 @@ def resolve( # Return a copy with only the relevant rules filtered = Policy( name=policy.name, - category=policy.category, + domain=policy.domain, services=policy.services, rules=relevant_rules, patterns=policy.patterns, anti_patterns=policy.anti_patterns, references=policy.references, - last_reviewed=policy.last_reviewed, ) matched.append(filtered) @@ -394,6 +378,108 @@ def format_for_prompt( return "\n".join(sections) + def resolve_for_stage( + self, + services: list[str], + iac_tool: str, + agent_name: str = "", + ) -> str: + """Resolve and format deterministic policies for a stage's services. + + Uses **exact service matching** (not embeddings) to find all + policies that apply to the named services. Returns a formatted + brief with the IaC-specific code patterns (terraform or bicep), + companion resources, and prohibitions. + """ + if not self._loaded: + self.load() + + if not services: + return "" + + svc_set = {s.lower() for s in services} + matched_policies = [] + for p in self._policies: + # Match by aggregate policy.services (legacy + new targets union) + policy_svcs = {s.lower() for s in p.services} + overlap = policy_svcs & svc_set + if not overlap: + # Also try per-rule targets[].services + rule_targets = { + s.lower() for r in p.rules for t in r.targets if isinstance(t, dict) for s in t.get("services", []) + } + overlap = rule_targets & svc_set + if not overlap: + continue + # Only include if the majority of the policy's services are in the stage, + # OR the policy is service-specific (1-2 services). + if len(policy_svcs) <= 2 or len(overlap) >= max(len(policy_svcs), 1) / 2: + matched_policies.append(p) + if not matched_policies: + return "" + + pattern_key = "terraform_pattern" if iac_tool == "terraform" else "bicep_pattern" + sections: list[str] = [] + + for policy in matched_policies: + rules = [ + r + for r in policy.rules + if r.severity == "required" and (not agent_name or not r.applies_to or agent_name in r.applies_to) + ] + if not rules: + continue + + sections.append(f"### {policy.name}") + + for rule in rules: + sections.append(f"\n**[{rule.id}] {rule.description}**") + if rule.rationale: + sections.append(f"Rationale: {rule.rationale}") + + # Find matching target entry for the requested services + for target in rule.targets: + if not isinstance(target, dict): + continue + target_svcs = {s.lower() for s in target.get("services", [])} + if target_svcs and not (target_svcs & svc_set): + continue # This target entry is for a different service + pattern = target.get(pattern_key, "") or "" + if isinstance(pattern, str) and pattern.strip(): + sections.append(f"```\n{pattern.strip()}\n```") + prohibitions = target.get("prohibitions", []) + if prohibitions: + for p in prohibitions: + sections.append(f"- NEVER: {p}") + + for cr in rule.companion_resources: + sections.append(f"\nCOMPANION RESOURCE: {cr.description}") + cr_pattern = getattr(cr, pattern_key, "") or "" + if cr_pattern.strip(): + sections.append(f"```\n{cr_pattern.strip()}\n```") + + prohibitions = [] # already handled per-target above + if prohibitions: + for p in prohibitions: + sections.append(f"- NEVER: {p}") + + sections.append("") + + if not sections: + return "" + + header = ( + "## MANDATORY RESOURCE POLICIES\n\n" + "The following policies define the REQUIRED baseline configuration for each resource.\n" + "You MUST include all properties, companion resources, and patterns specified below.\n" + "You MAY add additional properties required by the architecture (SKUs, database names,\n" + "app settings, etc.), but you must NEVER omit or contradict a policy directive.\n\n" + 'If a policy says "NEVER use X", do not use X under any circumstances.\n' + "If a policy provides exact code, use it as your starting template and extend as needed.\n" + ) + + return header + "\n".join(sections) + def list_policies(self) -> list[Policy]: """Return all loaded policies.""" if not self._loaded: @@ -401,31 +487,69 @@ def list_policies(self) -> list[Policy]: return list(self._policies) def _parse_policy(self, path: Path) -> Policy | None: - """Parse a single .policy.yaml file into a Policy object.""" + """Parse a single .policy.yaml file into a Policy object. + + Supports both the new unified format (flat top-level keys) and + the legacy format (apiVersion + metadata wrapper) for backward + compatibility during migration. + """ try: data: dict[str, Any] = yaml.safe_load(path.read_text(encoding="utf-8")) or {} except Exception: logger.warning("Failed to parse policy file: %s", path) return None - metadata = data.get("metadata", {}) - if not isinstance(metadata, dict): + if not isinstance(data, dict): return None + policy_name = path.stem.replace(".policy", "") + policy_domain = str(data.get("domain", "general")) + policy_description = str(data.get("description", "")) + policy_last_updated = str(data.get("last_updated", "")) + rules = [] + all_target_services: set[str] = set() for r in data.get("rules", []): if not isinstance(r, dict): continue + companions = [ + CompanionResource( + type=str(cr.get("type", "")), + description=str(cr.get("description", "")), + name=str(cr.get("name", "")), + terraform_pattern=str(cr.get("terraform_pattern", "")), + bicep_pattern=str(cr.get("bicep_pattern", "")), + ) + for cr in r.get("companion_resources", []) + if isinstance(cr, dict) + ] + # targets is a list of target blocks + targets_raw = r.get("targets", []) + if isinstance(targets_raw, dict): + # Normalize single dict to list + targets_raw = [targets_raw] + if not isinstance(targets_raw, list): + targets_raw = [] + for t in targets_raw: + if isinstance(t, dict): + all_target_services.update(t.get("services", [])) + rules.append( PolicyRule( id=str(r.get("id", "")), severity=str(r.get("severity", "optional")), description=str(r.get("description", "")), rationale=str(r.get("rationale", "")), + warning_message=str(r.get("warning_message", "")), applies_to=r.get("applies_to", []), + targets=targets_raw, + companion_resources=companions, ) ) + # Aggregate services from all per-rule targets + aggregate_services = list(all_target_services) + patterns = [] for p in data.get("patterns", []): if not isinstance(p, dict): @@ -439,12 +563,13 @@ def _parse_policy(self, path: Path) -> Policy | None: ) return Policy( - name=str(metadata.get("name", path.stem)), - category=str(metadata.get("category", "general")), - services=metadata.get("services", []), + name=policy_name, + domain=policy_domain, + description=policy_description, + last_updated=policy_last_updated, + services=aggregate_services, rules=rules, patterns=patterns, anti_patterns=data.get("anti_patterns", []), references=data.get("references", []), - last_reviewed=str(metadata.get("last_reviewed", "")), ) diff --git a/azext_prototype/governance/standards/bicep/__init__.py b/azext_prototype/governance/policies/azure/ai/__init__.py similarity index 100% rename from azext_prototype/governance/standards/bicep/__init__.py rename to azext_prototype/governance/policies/azure/ai/__init__.py diff --git a/azext_prototype/governance/policies/azure/ai/azure-ai-search.policy.yaml b/azext_prototype/governance/policies/azure/ai/azure-ai-search.policy.yaml new file mode 100644 index 0000000..9c425c5 --- /dev/null +++ b/azext_prototype/governance/policies/azure/ai/azure-ai-search.policy.yaml @@ -0,0 +1,218 @@ +kind: policy +domain: azure-ai +description: Governance policies for Azure Ai Search +last_updated: '2026-03-27' +rules: +- id: AZ-AIS-001 + severity: required + description: Deploy Azure AI Search with managed identity, disabled API key auth, and no public access + rationale: API keys cannot be scoped or audited; managed identity with RBAC provides fine-grained access control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-search + description: Private endpoint for Azure AI Search to eliminate public network exposure + terraform_pattern: | + resource "azapi_resource" "pe_search" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.search_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "search-connection" + properties = { + privateLinkServiceId = azapi_resource.search.id + groupIds = ["searchService"] + } + } + ] + } + } + } + bicep_pattern: | + resource peSearch 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${searchName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'search-connection' + properties: { + privateLinkServiceId: search.id + groupIds: ['searchService'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.search.windows.net + description: Private DNS zone for Azure AI Search private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-search + description: Diagnostic settings to route operational and query logs to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_search" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.search_name}" + parent_id = azapi_resource.search.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagSearch 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${searchName}' + scope: search + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Search Index Data Reader / Contributor + description: RBAC role assignment granting consuming identity the appropriate Search data-plane role + targets: + - services: + - Microsoft.Search/searchServices + terraform_pattern: | + resource "azapi_resource" "search" { + type = "Microsoft.Search/searchServices@2024-03-01-preview" + name = var.search_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = var.sku_name # "basic", "standard", "standard2", "standard3" + } + properties = { + hostingMode = "default" + publicNetworkAccess = "disabled" + disableLocalAuth = true + authOptions = { + aadOrApiKey = { + aadAuthFailureMode = "http401WithBearerChallenge" + } + } + encryptionWithCmk = { + enforcement = "Enabled" + } + replicaCount = var.replica_count + partitionCount = var.partition_count + } + } + } + bicep_pattern: | + resource search 'Microsoft.Search/searchServices@2024-03-01-preview' = { + name: searchName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + } + properties: { + hostingMode: 'default' + publicNetworkAccess: 'disabled' + disableLocalAuth: true + authOptions: { + aadOrApiKey: { + aadAuthFailureMode: 'http401WithBearerChallenge' + } + } + encryptionWithCmk: { + enforcement: 'Enabled' + } + replicaCount: replicaCount + partitionCount: partitionCount + } + } + prohibitions: + - Never hardcode search admin keys or query keys in source code or IaC + - Never set disableLocalAuth to false — always use Microsoft Entra authentication + - Never set publicNetworkAccess to enabled without compensating network controls + - Never use admin keys for query operations — use query keys or RBAC +- id: AZ-AIS-002 + severity: recommended + description: Configure semantic ranking and vector search with appropriate dimensions + rationale: Semantic ranker improves relevance; vector dimensions must match the embedding model + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Search/searchServices +- id: AZ-AIS-003 + severity: recommended + description: Enable customer-managed key encryption for indexes containing sensitive data + rationale: CMK encryption provides an additional layer of control over data-at-rest encryption + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Search/searchServices +patterns: +- name: Azure AI Search with private endpoint and RBAC + description: Secure search service with no public access, managed identity, and private connectivity +anti_patterns: +- description: Do not use API key authentication for Azure AI Search + instead: Set disableLocalAuth=true and use RBAC with Search Index Data Reader/Contributor roles +- description: Do not leave publicNetworkAccess enabled + instead: Set publicNetworkAccess to disabled and use private endpoints +references: +- title: Azure AI Search security overview + url: https://learn.microsoft.com/azure/search/search-security-overview +- title: Azure AI Search RBAC + url: https://learn.microsoft.com/azure/search/search-security-rbac diff --git a/azext_prototype/governance/policies/azure/ai/azure-openai.policy.yaml b/azext_prototype/governance/policies/azure/ai/azure-openai.policy.yaml new file mode 100644 index 0000000..0ffc80c --- /dev/null +++ b/azext_prototype/governance/policies/azure/ai/azure-openai.policy.yaml @@ -0,0 +1,267 @@ +kind: policy +domain: azure-ai +description: Governance policies for Azure Openai +last_updated: '2026-03-27' +rules: +- id: AZ-AOI-001 + severity: required + description: Deploy Azure OpenAI with managed identity and disable API key authentication + rationale: API keys are long-lived credentials that cannot be scoped; managed identity eliminates credential management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-openai + description: Private endpoint for Azure OpenAI to eliminate public network exposure + terraform_pattern: | + resource "azapi_resource" "pe_openai" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.openai_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "openai-connection" + properties = { + privateLinkServiceId = azapi_resource.openai.id + groupIds = ["account"] + } + } + ] + } + } + } + bicep_pattern: | + resource peOpenai 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${openaiName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'openai-connection' + properties: { + privateLinkServiceId: openai.id + groupIds: ['account'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.openai.azure.com + description: Private DNS zone for Azure OpenAI private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-openai + description: Diagnostic settings to route audit and request logs to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_openai" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.openai_name}" + parent_id = azapi_resource.openai.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagOpenai 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${openaiName}' + scope: openai + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Cognitive Services OpenAI User + description: RBAC role assignment granting consuming identity the Cognitive Services OpenAI User role + targets: + - services: + - Microsoft.CognitiveServices/accounts + terraform_pattern: | + resource "azapi_resource" "openai" { + type = "Microsoft.CognitiveServices/accounts@2024-04-01-preview" + name = var.openai_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + kind = "OpenAI" + sku = { + name = var.sku_name # "S0" + } + properties = { + customSubDomainName = var.openai_subdomain + disableLocalAuth = true + publicNetworkAccess = "Disabled" + networkAcls = { + defaultAction = "Deny" + ipRules = [] + } + encryption = { + keySource = "Microsoft.CognitiveServices" + } + } + } + } + bicep_pattern: | + resource openai 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = { + name: openaiName + location: location + kind: 'OpenAI' + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName // 'S0' + } + properties: { + customSubDomainName: openaiSubdomain + disableLocalAuth: true + publicNetworkAccess: 'Disabled' + networkAcls: { + defaultAction: 'Deny' + ipRules: [] + } + encryption: { + keySource: 'Microsoft.CognitiveServices' + } + } + } + prohibitions: + - Never hardcode API keys in source code or IaC templates + - Never set disableLocalAuth to false — always disable key-based authentication + - Never set publicNetworkAccess to Enabled without compensating network controls + - Never embed endpoint URLs with keys in application configuration + - Never use Cognitive Services Contributor role when Cognitive Services OpenAI User suffices +- id: AZ-AOI-002 + severity: required + description: Deploy model instances with explicit capacity and version pinning + rationale: Unpinned model versions cause non-deterministic behavior; unset capacity causes throttling + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.CognitiveServices/accounts + terraform_pattern: | + resource "azapi_resource" "openai_deployment" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview" + name = var.deployment_name + parent_id = azapi_resource.openai.id + + body = { + sku = { + name = "Standard" + capacity = var.tpm_capacity # tokens-per-minute in thousands + } + properties = { + model = { + format = "OpenAI" + name = var.model_name # e.g. "gpt-4o" + version = var.model_version # e.g. "2024-08-06" + } + versionUpgradeOption = "NoAutoUpgrade" + } + } + } + bicep_pattern: | + resource openaiDeployment 'Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview' = { + name: deploymentName + parent: openai + sku: { + name: 'Standard' + capacity: tpmCapacity + } + properties: { + model: { + format: 'OpenAI' + name: modelName + version: modelVersion + } + versionUpgradeOption: 'NoAutoUpgrade' + } + } + prohibitions: + - Never omit model version — always pin to a specific version string + - Never use versionUpgradeOption 'OnceNewDefaultVersionAvailable' in production + - Never deploy without explicit capacity (sku.capacity) +- id: AZ-AOI-003 + severity: recommended + description: Implement content filtering policies on all deployments + rationale: Content filtering prevents misuse and ensures responsible AI compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.CognitiveServices/accounts +- id: AZ-AOI-004 + severity: recommended + description: Configure rate limiting and retry logic in consuming applications + rationale: Azure OpenAI enforces TPM and RPM limits; clients must handle 429 responses gracefully + applies_to: + - app-developer + - csharp-developer + - python-developer + - cloud-architect + targets: + - services: + - Microsoft.CognitiveServices/accounts +patterns: +- name: Azure OpenAI with private endpoint and RBAC + description: Secure Azure OpenAI deployment with no public access, managed identity, and private connectivity +anti_patterns: +- description: Do not use API key authentication for Azure OpenAI + instead: Set disableLocalAuth=true and use managed identity with Cognitive Services OpenAI User role +- description: Do not deploy models without version pinning + instead: Always specify model.version and set versionUpgradeOption to NoAutoUpgrade +- description: Do not leave publicNetworkAccess as Enabled + instead: Set publicNetworkAccess to Disabled and use private endpoints +references: +- title: Azure OpenAI Service documentation + url: https://learn.microsoft.com/azure/ai-services/openai/overview +- title: Azure OpenAI networking and security + url: https://learn.microsoft.com/azure/ai-services/openai/how-to/managed-identity diff --git a/azext_prototype/governance/policies/azure/ai/bot-service.policy.yaml b/azext_prototype/governance/policies/azure/ai/bot-service.policy.yaml new file mode 100644 index 0000000..8e18416 --- /dev/null +++ b/azext_prototype/governance/policies/azure/ai/bot-service.policy.yaml @@ -0,0 +1,177 @@ +kind: policy +domain: azure-ai +description: Governance policies for Bot Service +last_updated: '2026-03-27' +rules: +- id: AZ-BOT-001 + severity: required + description: Deploy Azure Bot Service with managed identity and isolated network configuration + rationale: Bot Service handles user conversations; managed identity removes credential management for backend connections + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31 + name: id-bot + description: User-assigned managed identity for Bot Service MSA authentication + terraform_pattern: | + resource "azapi_resource" "bot_identity" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31" + name = "id-${var.bot_name}" + location = var.location + parent_id = var.resource_group_id + } + bicep_pattern: | + resource botIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { + name: 'id-${botName}' + location: location + } + - type: Microsoft.BotService/botServices/channels@2022-09-15 + name: DirectLineChannel + description: Direct Line channel with enhanced authentication for secure client communication + terraform_pattern: | + resource "azapi_resource" "bot_directline" { + type = "Microsoft.BotService/botServices/channels@2022-09-15" + name = "DirectLineChannel" + parent_id = azapi_resource.bot.id + + body = { + properties = { + channelName = "DirectLineChannel" + properties = { + sites = [ + { + siteName = "default" + isEnabled = true + isV1Enabled = false + isV3Enabled = true + isSecureSiteEnabled = true + isBlockUserUploadEnabled = false + trustedOrigins = var.trusted_origins + } + ] + DirectLineEmbedCode = null + } + } + } + } + bicep_pattern: | + resource botDirectLine 'Microsoft.BotService/botServices/channels@2022-09-15' = { + name: 'DirectLineChannel' + parent: bot + properties: { + channelName: 'DirectLineChannel' + properties: { + sites: [ + { + siteName: 'default' + isEnabled: true + isV1Enabled: false + isV3Enabled: true + isSecureSiteEnabled: true + isBlockUserUploadEnabled: false + trustedOrigins: trustedOrigins + } + ] + } + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-bot + description: Diagnostic settings to route bot activity logs to Log Analytics + targets: + - services: + - Microsoft.BotService/botServices + terraform_pattern: | + resource "azapi_resource" "bot" { + type = "Microsoft.BotService/botServices@2022-09-15" + name = var.bot_name + location = "global" + parent_id = var.resource_group_id + + body = { + kind = "azurebot" + sku = { + name = var.sku_name # "F0" or "S1" + } + properties = { + displayName = var.bot_display_name + endpoint = var.bot_endpoint + msaAppId = var.msa_app_id + msaAppType = "UserAssignedMSI" + msaAppMSIResourceId = var.user_assigned_identity_id + msaAppTenantId = var.tenant_id + disableLocalAuth = true + isStreamingSupported = true + publicNetworkAccess = "Disabled" + tenantId = var.tenant_id + } + } + } + bicep_pattern: | + resource bot 'Microsoft.BotService/botServices@2022-09-15' = { + name: botName + location: 'global' + kind: 'azurebot' + sku: { + name: skuName + } + properties: { + displayName: botDisplayName + endpoint: botEndpoint + msaAppId: msaAppId + msaAppType: 'UserAssignedMSI' + msaAppMSIResourceId: userAssignedIdentityId + msaAppTenantId: tenantId + disableLocalAuth: true + isStreamingSupported: true + publicNetworkAccess: 'Disabled' + tenantId: tenantId + } + } + prohibitions: + - Never hardcode MSA app passwords or client secrets in IaC + - Never use msaAppType 'SingleTenant' with hardcoded credentials — use UserAssignedMSI + - Never set disableLocalAuth to false + - Never enable V1 Direct Line protocol — it lacks enhanced authentication + - Never leave trustedOrigins empty on Direct Line channels with isSecureSiteEnabled +- id: AZ-BOT-002 + severity: required + description: Configure Direct Line channels with enhanced authentication and trusted origins + rationale: Enhanced authentication prevents token theft and ensures only trusted origins can embed the bot + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.BotService/botServices +- id: AZ-BOT-003 + severity: recommended + description: Enable Application Insights for bot telemetry and conversation analytics + rationale: Bot telemetry provides conversation flow analysis, error tracking, and user engagement metrics + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.BotService/botServices +patterns: +- name: Bot Service with managed identity and secure Direct Line + description: Azure Bot with user-assigned identity, enhanced auth, and trusted origins +anti_patterns: +- description: Do not use MSA app passwords for bot authentication + instead: Use msaAppType=UserAssignedMSI with a user-assigned managed identity +- description: Do not enable Direct Line V1 protocol + instead: Use V3 with isSecureSiteEnabled=true and configure trustedOrigins +references: +- title: Azure Bot Service security best practices + url: https://learn.microsoft.com/azure/bot-service/bot-builder-security-guidelines +- title: Bot Direct Line enhanced authentication + url: https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication diff --git a/azext_prototype/governance/policies/azure/ai/cognitive-services.policy.yaml b/azext_prototype/governance/policies/azure/ai/cognitive-services.policy.yaml new file mode 100644 index 0000000..1c0a96a --- /dev/null +++ b/azext_prototype/governance/policies/azure/ai/cognitive-services.policy.yaml @@ -0,0 +1,213 @@ +kind: policy +domain: azure-ai +description: Governance policies for Cognitive Services +last_updated: '2026-03-27' +rules: +- id: AZ-CS-001 + severity: required + description: Deploy Cognitive Services with managed identity, disabled local auth, and no public access + rationale: API keys are shared secrets that cannot be scoped; managed identity provides auditable, per-service access + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-cognitive + description: Private endpoint for Cognitive Services to eliminate public network exposure + terraform_pattern: | + resource "azapi_resource" "pe_cognitive" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.cognitive_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "cognitive-connection" + properties = { + privateLinkServiceId = azapi_resource.cognitive.id + groupIds = ["account"] + } + } + ] + } + } + } + bicep_pattern: | + resource peCognitive 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${cognitiveName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'cognitive-connection' + properties: { + privateLinkServiceId: cognitive.id + groupIds: ['account'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.cognitiveservices.azure.com + description: Private DNS zone for Cognitive Services private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-cognitive + description: Diagnostic settings to route audit and request logs to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_cognitive" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.cognitive_name}" + parent_id = azapi_resource.cognitive.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagCognitive 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${cognitiveName}' + scope: cognitive + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Cognitive Services User + description: RBAC role assignment granting consuming identity the Cognitive Services User role + targets: + - services: + - Microsoft.CognitiveServices/accounts + terraform_pattern: | + resource "azapi_resource" "cognitive" { + type = "Microsoft.CognitiveServices/accounts@2024-04-01-preview" + name = var.cognitive_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + kind = var.cognitive_kind # "CognitiveServices", "TextAnalytics", "ComputerVision", etc. + sku = { + name = var.sku_name # "S0", "S1", "F0" + } + properties = { + customSubDomainName = var.cognitive_subdomain + disableLocalAuth = true + publicNetworkAccess = "Disabled" + networkAcls = { + defaultAction = "Deny" + ipRules = [] + } + encryption = { + keySource = "Microsoft.CognitiveServices" + } + apiProperties = {} + } + } + } + bicep_pattern: | + resource cognitive 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = { + name: cognitiveName + location: location + kind: cognitiveKind + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + } + properties: { + customSubDomainName: cognitiveSubdomain + disableLocalAuth: true + publicNetworkAccess: 'Disabled' + networkAcls: { + defaultAction: 'Deny' + ipRules: [] + } + encryption: { + keySource: 'Microsoft.CognitiveServices' + } + } + } + prohibitions: + - Never hardcode API keys in source code or IaC templates + - Never set disableLocalAuth to false — always disable key-based authentication + - Never set publicNetworkAccess to Enabled without compensating network controls + - Never use Cognitive Services Contributor when Cognitive Services User suffices + - Never omit customSubDomainName — it is required for Microsoft Entra authentication +- id: AZ-CS-002 + severity: required + description: Set customSubDomainName on all Cognitive Services accounts + rationale: Custom subdomain is required for Microsoft Entra authentication and private endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.CognitiveServices/accounts +- id: AZ-CS-003 + severity: recommended + description: Enable customer-managed key encryption for accounts processing sensitive data + rationale: CMK provides additional control over data-at-rest encryption beyond platform-managed keys + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.CognitiveServices/accounts +patterns: +- name: Cognitive Services with private endpoint and RBAC + description: Secure Cognitive Services deployment with no public access, managed identity, and diagnostics +anti_patterns: +- description: Do not use API key authentication for Cognitive Services + instead: Set disableLocalAuth=true and use managed identity with Cognitive Services User role +- description: Do not deploy without a customSubDomainName + instead: Always set customSubDomainName — it is required for Entra auth and private endpoints +references: +- title: Cognitive Services security baseline + url: https://learn.microsoft.com/azure/ai-services/security-baseline +- title: Configure virtual networks for Cognitive Services + url: https://learn.microsoft.com/azure/ai-services/cognitive-services-virtual-networks diff --git a/azext_prototype/governance/policies/azure/ai/machine-learning.policy.yaml b/azext_prototype/governance/policies/azure/ai/machine-learning.policy.yaml new file mode 100644 index 0000000..2cc56c9 --- /dev/null +++ b/azext_prototype/governance/policies/azure/ai/machine-learning.policy.yaml @@ -0,0 +1,280 @@ +kind: policy +domain: azure-ai +description: Governance policies for Machine Learning +last_updated: '2026-03-27' +rules: +- id: AZ-ML-001 + severity: required + description: Deploy Azure Machine Learning workspace with managed identity, high business impact, and no public access + rationale: ML workspaces handle sensitive training data and models; managed identity eliminates credential sprawl + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-ml-workspace + description: Private endpoint for ML workspace to eliminate public network exposure + terraform_pattern: | + resource "azapi_resource" "pe_ml" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.ml_workspace_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "ml-connection" + properties = { + privateLinkServiceId = azapi_resource.ml_workspace.id + groupIds = ["amlworkspace"] + } + } + ] + } + } + } + bicep_pattern: | + resource peMl 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${mlWorkspaceName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'ml-connection' + properties: { + privateLinkServiceId: mlWorkspace.id + groupIds: ['amlworkspace'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.api.azureml.ms + description: Private DNS zone for ML workspace API endpoint + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.notebooks.azure.net + description: Private DNS zone for ML workspace notebook endpoint + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-ml-workspace + description: Diagnostic settings to route ML workspace activity logs to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_ml" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.ml_workspace_name}" + parent_id = azapi_resource.ml_workspace.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagMl 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${mlWorkspaceName}' + scope: mlWorkspace + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: AzureML Data Scientist / Compute Operator + description: RBAC role assignments for data scientists and compute operators + targets: + - services: + - Microsoft.MachineLearningServices/workspaces + terraform_pattern: | + resource "azapi_resource" "ml_workspace" { + type = "Microsoft.MachineLearningServices/workspaces@2024-04-01" + name = var.ml_workspace_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Basic" + tier = "Basic" + } + properties = { + friendlyName = var.ml_workspace_name + storageAccount = var.storage_account_id + keyVault = var.key_vault_id + applicationInsights = var.app_insights_id + containerRegistry = var.container_registry_id + publicNetworkAccess = "Disabled" + hbiWorkspace = true + managedNetwork = { + isolationMode = "AllowOnlyApprovedOutbound" + } + encryption = { + status = "Enabled" + keyVaultProperties = { + keyVaultArmId = var.key_vault_id + keyIdentifier = var.cmk_key_id + } + } + v1LegacyMode = false + } + } + } + bicep_pattern: | + resource mlWorkspace 'Microsoft.MachineLearningServices/workspaces@2024-04-01' = { + name: mlWorkspaceName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Basic' + tier: 'Basic' + } + properties: { + friendlyName: mlWorkspaceName + storageAccount: storageAccountId + keyVault: keyVaultId + applicationInsights: appInsightsId + containerRegistry: containerRegistryId + publicNetworkAccess: 'Disabled' + hbiWorkspace: true + managedNetwork: { + isolationMode: 'AllowOnlyApprovedOutbound' + } + encryption: { + status: 'Enabled' + keyVaultProperties: { + keyVaultArmId: keyVaultId + keyIdentifier: cmkKeyId + } + } + v1LegacyMode: false + } + } + prohibitions: + - Never hardcode storage account keys or workspace secrets in IaC + - Never set publicNetworkAccess to Enabled without managed network isolation + - Never disable hbiWorkspace when processing sensitive/regulated data + - Never use v1LegacyMode — always use v2 APIs + - Never create compute instances without managed identity + - Never skip associated Key Vault, Storage Account, or Application Insights dependencies +- id: AZ-ML-002 + severity: required + description: Deploy compute instances and clusters with managed identity and no public IP + rationale: Compute resources with public IPs and no identity create attack surface and credential risk + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.MachineLearningServices/workspaces + terraform_pattern: | + resource "azapi_resource" "ml_compute" { + type = "Microsoft.MachineLearningServices/workspaces/computes@2024-04-01" + name = var.compute_name + parent_id = azapi_resource.ml_workspace.id + location = var.location + + body = { + properties = { + computeType = "ComputeInstance" + properties = { + vmSize = var.vm_size + enableNodePublicIp = false + idleTimeBeforeShutdown = "PT30M" + setupScripts = null + personalComputeInstanceSettings = null + } + } + identity = { + type = "SystemAssigned" + } + } + } + bicep_pattern: | + resource mlCompute 'Microsoft.MachineLearningServices/workspaces/computes@2024-04-01' = { + name: computeName + parent: mlWorkspace + location: location + properties: { + computeType: 'ComputeInstance' + properties: { + vmSize: vmSize + enableNodePublicIp: false + idleTimeBeforeShutdown: 'PT30M' + } + } + identity: { + type: 'SystemAssigned' + } + } + prohibitions: + - Never set enableNodePublicIp to true + - Never create compute without managed identity + - Never skip idle shutdown configuration — set idleTimeBeforeShutdown to avoid cost waste +- id: AZ-ML-003 + severity: recommended + description: Use managed online endpoints with managed identity for model serving + rationale: Managed endpoints handle scaling, versioning, and traffic splitting; managed identity secures model access + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.MachineLearningServices/workspaces +patterns: +- name: ML workspace with managed network and CMK + description: Secure ML workspace with network isolation, CMK encryption, and associated resources +anti_patterns: +- description: Do not deploy ML workspace without associated Key Vault, Storage, and App Insights + instead: Always provision the four required dependency resources before workspace creation +- description: Do not use workspace access keys for programmatic access + instead: Use managed identity and RBAC role assignments (AzureML Data Scientist) +- description: Do not deploy compute with public IPs + instead: Set enableNodePublicIp=false and use managed network isolation +references: +- title: Azure Machine Learning security baseline + url: https://learn.microsoft.com/azure/machine-learning/security-baseline +- title: Configure managed network isolation + url: https://learn.microsoft.com/azure/machine-learning/how-to-managed-network diff --git a/azext_prototype/governance/policies/azure/app-service.policy.yaml b/azext_prototype/governance/policies/azure/app-service.policy.yaml deleted file mode 100644 index 7d814e6..0000000 --- a/azext_prototype/governance/policies/azure/app-service.policy.yaml +++ /dev/null @@ -1,89 +0,0 @@ -apiVersion: v1 -kind: policy -metadata: - name: app-service - category: azure - services: [app-service, functions] - last_reviewed: "2026-02-01" - -rules: - - id: AS-001 - severity: required - description: "Enforce HTTPS-only — redirect all HTTP traffic to HTTPS" - rationale: "Prevents cleartext data transmission and man-in-the-middle attacks" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [app-service, functions] - require_config: [https_only] - error_message: "Service '{service_name}' ({service_type}) missing https_only: true" - - - id: AS-002 - severity: required - description: "Set minimum TLS version to 1.2" - rationale: "TLS 1.0 and 1.1 have known vulnerabilities" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [app-service, functions] - require_config: [min_tls_version] - error_message: "Service '{service_name}' ({service_type}) missing min_tls_version: '1.2'" - - - id: AS-003 - severity: required - description: "Use managed identity for accessing Azure resources" - rationale: "Eliminates credential management; SDK handles token acquisition" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [app-service, functions] - require_config: [identity] - error_message: "Service '{service_name}' ({service_type}) missing managed identity configuration" - - - id: AS-004 - severity: required - description: "Deploy into a VNET-integrated subnet for backend connectivity" - rationale: "Enables private access to databases, Key Vault, and other PaaS services" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - - - id: AS-005 - severity: recommended - description: "Use deployment slots for zero-downtime deployments in production" - rationale: "Slot swaps are atomic and support rollback" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: AS-006 - severity: recommended - description: "Enable diagnostic logging to Log Analytics workspace" - rationale: "Enables monitoring, alerting, and incident investigation" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent] - - - id: AS-007 - severity: recommended - description: "Use App Service Authentication (EasyAuth) or custom middleware for user-facing apps" - rationale: "Built-in auth handles token validation without custom code" - applies_to: [cloud-architect, app-developer, biz-analyst] - -patterns: - - name: "App Service with managed identity and VNET" - description: "Standard App Service deployment with security baseline" - example: | - resource "azurerm_linux_web_app" "main" { - https_only = true - identity { - type = "SystemAssigned" - } - site_config { - minimum_tls_version = "1.2" - vnet_route_all_enabled = true - } - } - -anti_patterns: - - description: "Do not set https_only = false or omit HTTPS enforcement" - instead: "Always set https_only = true on App Service and Functions" - - description: "Do not store secrets in App Settings as plaintext" - instead: "Use Key Vault references (@Microsoft.KeyVault(SecretUri=...))" - -references: - - title: "App Service security best practices" - url: "https://learn.microsoft.com/azure/app-service/overview-security" - - title: "App Service VNET integration" - url: "https://learn.microsoft.com/azure/app-service/overview-vnet-integration" diff --git a/azext_prototype/governance/standards/terraform/__init__.py b/azext_prototype/governance/policies/azure/compute/__init__.py similarity index 100% rename from azext_prototype/governance/standards/terraform/__init__.py rename to azext_prototype/governance/policies/azure/compute/__init__.py diff --git a/azext_prototype/governance/policies/azure/compute/aks.policy.yaml b/azext_prototype/governance/policies/azure/compute/aks.policy.yaml new file mode 100644 index 0000000..93cdf1e --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/aks.policy.yaml @@ -0,0 +1,431 @@ +kind: policy +domain: azure-compute +description: Governance policies for AKS +last_updated: '2026-03-27' +rules: +- id: AZ-AKS-001 + severity: required + description: Create AKS cluster with Azure AD RBAC, workload identity, private cluster, and managed identity + rationale: Azure AD RBAC centralizes access control; workload identity eliminates pod-level secrets; private cluster prevents + API server exposure; managed identity eliminates service principal credential management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.{location}.azmk8s.io + description: Private DNS zone for AKS private cluster API server resolution + terraform_pattern: | + resource "azapi_resource" "aks_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.${var.location}.azmk8s.io" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "aks_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.aks_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + bicep_pattern: | + resource aksDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.${location}.azmk8s.io' + location: 'global' + } + + resource aksDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: aksDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Network Contributor + description: Network Contributor role for AKS identity on the VNet subnet + terraform_pattern: | + resource "azapi_resource" "aks_network_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.aks_network_role_name + parent_id = var.aks_subnet_id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" + principalId = azapi_resource.user_assigned_identity.output.properties.principalId + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource aksNetworkContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: aksSubnet + name: aksNetworkRoleName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4d97b98b-1d4f-4787-a291-c67834d212e7') + principalId: userAssignedIdentity.properties.principalId + principalType: 'ServicePrincipal' + } + } + targets: + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + location = var.location + parent_id = azapi_resource.resource_group.id + + identity { + type = "UserAssigned" + identity_ids = [azapi_resource.user_assigned_identity.id] + } + + body = { + sku = { + name = "Base" + tier = "Free" + } + properties = { + kubernetesVersion = var.kubernetes_version + dnsPrefix = var.aks_dns_prefix + enableRBAC = true + aadProfile = { + managed = true + enableAzureRBAC = true + adminGroupObjectIDs = [var.aks_admin_group_object_id] + } + apiServerAccessProfile = { + enablePrivateCluster = true + enablePrivateClusterPublicFQDN = false + } + networkProfile = { + networkPlugin = "azure" + networkPolicy = "calico" + serviceCidr = "10.0.0.0/16" + dnsServiceIP = "10.0.0.10" + loadBalancerSku = "standard" + } + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 1 + vmSize = "Standard_D2s_v5" + osType = "Linux" + osSKU = "AzureLinux" + vnetSubnetID = var.aks_subnet_id + enableAutoScaling = true + minCount = 1 + maxCount = 3 + } + ] + oidcIssuerProfile = { + enabled = true + } + securityProfile = { + workloadIdentity = { + enabled = true + } + } + addonProfiles = { + omsagent = { + enabled = true + config = { + logAnalyticsWorkspaceResourceID = var.log_analytics_workspace_id + } + } + } + } + } + } + bicep_pattern: | + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${userAssignedIdentity.id}': {} + } + } + sku: { + name: 'Base' + tier: 'Free' + } + properties: { + kubernetesVersion: kubernetesVersion + dnsPrefix: aksDnsPrefix + enableRBAC: true + aadProfile: { + managed: true + enableAzureRBAC: true + adminGroupObjectIDs: [ + aksAdminGroupObjectId + ] + } + apiServerAccessProfile: { + enablePrivateCluster: true + enablePrivateClusterPublicFQDN: false + } + networkProfile: { + networkPlugin: 'azure' + networkPolicy: 'calico' + serviceCidr: '10.0.0.0/16' + dnsServiceIP: '10.0.0.10' + loadBalancerSku: 'standard' + } + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 1 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + osSKU: 'AzureLinux' + vnetSubnetID: aksSubnetId + enableAutoScaling: true + minCount: 1 + maxCount: 3 + } + ] + oidcIssuerProfile: { + enabled: true + } + securityProfile: { + workloadIdentity: { + enabled: true + } + } + addonProfiles: { + omsagent: { + enabled: true + config: { + logAnalyticsWorkspaceResourceID: logAnalyticsWorkspace.id + } + } + } + } + } + prohibitions: + - NEVER set enableRBAC to false — Kubernetes RBAC must always be enabled + - NEVER set enablePrivateCluster to false — API server must not be publicly accessible + - NEVER use service principal (servicePrincipalProfile) — use managed identity + - NEVER use kubenet network plugin — use azure CNI for VNet integration + - NEVER disable workload identity — it replaces pod identity and AAD pod identity (both deprecated) + - NEVER use local accounts — set disableLocalAccounts to true in production +- id: AZ-AKS-002 + severity: required + description: Enable OMS agent addon for container monitoring + rationale: Container Insights provides CPU, memory, pod health, and log collection for troubleshooting + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.ContainerService/managedClusters +- id: AZ-AKS-003 + severity: required + description: Use VNet integration with azure CNI for network policy support + rationale: Azure CNI assigns pod IPs from the VNet, enabling NSGs, network policies, and private endpoint connectivity + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + when_services_present: + - aks + require_service: + - virtual-network + error_message: Template with AKS must include a virtual-network service for VNet integration + targets: + - services: + - Microsoft.ContainerService/managedClusters +- id: AZ-AKS-004 + severity: recommended + description: Use Free tier for POC, Standard tier for production + rationale: Free tier has limited SLA; Standard provides 99.95% uptime SLA + applies_to: + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.ContainerService/managedClusters +- id: AZ-AKS-005 + severity: recommended + description: Enable cluster autoscaler on node pools + rationale: Automatically scales nodes based on pod scheduling demand; reduces idle cost + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.ContainerService/managedClusters +- id: AZ-AKS-006 + severity: required + description: Enable Microsoft Defender for Containers on the cluster + rationale: 'WAF Security: Provides runtime threat detection, vulnerability scanning, and security monitoring for clusters, + containers, and applications' + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + resource "azapi_resource" "defender_containers" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "Containers" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + bicep_pattern: | + resource defenderContainers 'Microsoft.Security/pricings@2024-01-01' = { + name: 'Containers' + properties: { + pricingTier: 'Standard' + } + } +- id: AZ-AKS-007 + severity: required + description: Enable Azure Policy addon for AKS to enforce pod security and compliance + rationale: 'WAF Security: Azure Policy applies at-scale enforcement and safeguards on clusters in a centralized, consistent + manner, controlling pod functions and detecting policy violations' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + targets: + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # Add to the AKS cluster properties in AKS-001: + # addonProfiles = { + # azurepolicy = { + # enabled = true + # } + # } + bicep_pattern: | + // Add to the AKS cluster properties in AKS-001: + // addonProfiles: { + // azurepolicy: { + // enabled: true + // } + // } +- id: AZ-AKS-008 + severity: recommended + description: Disable local accounts and enforce Microsoft Entra ID-only authentication + rationale: 'WAF Security: Disabling local accounts ensures all cluster access flows through Microsoft Entra ID, providing + centralized identity and auditable access control' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + targets: + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # Add to the AKS cluster properties in AKS-001: + # properties = { + # disableLocalAccounts = true + # } + bicep_pattern: | + // Add to the AKS cluster properties in AKS-001: + // disableLocalAccounts: true +- id: AZ-AKS-009 + severity: recommended + description: Use availability zones for AKS node pools + rationale: 'WAF Reliability: Distributes AKS agent nodes across physically separate datacenters, ensuring nodes continue + running even if one zone goes down' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # Add to agentPoolProfiles in AKS-001: + # availabilityZones = ["1", "2", "3"] + bicep_pattern: | + // Add to agentPoolProfiles in AKS-001: + // availabilityZones: ['1', '2', '3'] +- id: AZ-AKS-010 + severity: recommended + description: Use NAT gateway for clusters with many concurrent outbound connections + rationale: 'WAF Reliability: NAT Gateway supports reliable egress traffic at scale, avoiding reliability problems from Azure + Load Balancer SNAT port exhaustion' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ContainerService/managedClusters +- id: AZ-AKS-011 + severity: recommended + description: Use the AKS uptime SLA (Standard tier) for production-grade clusters + rationale: 'WAF Reliability: Standard tier provides 99.95% uptime SLA for the Kubernetes API server endpoint, higher availability + guarantees than the Free tier' + applies_to: + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.ContainerService/managedClusters +patterns: +- name: AKS with Azure AD RBAC and workload identity + description: Complete AKS deployment with private cluster, Azure AD RBAC, workload identity, VNet integration, and container + monitoring +anti_patterns: +- description: Do not use service principal for AKS identity + instead: Use user-assigned managed identity +- description: Do not expose API server publicly + instead: Enable private cluster with enablePrivateCluster = true +- description: Do not use kubenet network plugin + instead: Use azure CNI for full VNet integration +- description: Do not use pod identity (deprecated) + instead: Use workload identity with OIDC issuer +references: +- title: AKS best practices + url: https://learn.microsoft.com/azure/aks/best-practices +- title: AKS private clusters + url: https://learn.microsoft.com/azure/aks/private-clusters +- title: AKS workload identity + url: https://learn.microsoft.com/azure/aks/workload-identity-overview +- title: AKS Azure AD integration + url: https://learn.microsoft.com/azure/aks/managed-azure-ad +- title: 'WAF: AKS service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-kubernetes-service +- title: Microsoft Defender for Containers + url: https://learn.microsoft.com/azure/defender-for-cloud/defender-for-containers-introduction +- title: Azure Policy for AKS + url: https://learn.microsoft.com/azure/aks/use-azure-policy diff --git a/azext_prototype/governance/policies/azure/compute/batch.policy.yaml b/azext_prototype/governance/policies/azure/compute/batch.policy.yaml new file mode 100644 index 0000000..f253254 --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/batch.policy.yaml @@ -0,0 +1,251 @@ +kind: policy +domain: azure-compute +description: Governance policies for Batch +last_updated: '2026-03-27' +rules: +- id: AZ-BATCH-001 + severity: required + description: Deploy Azure Batch account with managed identity, no public access, and user-subscription pool allocation mode + rationale: User-subscription mode puts VMs in your subscription for VNet control; managed identity eliminates shared key + usage + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-batch + description: Private endpoint for Batch account management plane + terraform_pattern: | + resource "azapi_resource" "pe_batch" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.batch_account_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "batch-connection" + properties = { + privateLinkServiceId = azapi_resource.batch_account.id + groupIds = ["batchAccount"] + } + } + ] + } + } + } + bicep_pattern: | + resource peBatch 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${batchAccountName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'batch-connection' + properties: { + privateLinkServiceId: batchAccount.id + groupIds: ['batchAccount'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.batch.azure.com + description: Private DNS zone for Batch account private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-batch + description: Diagnostic settings to route Batch service logs and task events to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_batch" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.batch_account_name}" + parent_id = azapi_resource.batch_account.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagBatch 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${batchAccountName}' + scope: batchAccount + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Batch Account Contributor + description: RBAC role assignment for Batch account management and pool operations + targets: + - services: + - Microsoft.Batch/batchAccounts + terraform_pattern: | + resource "azapi_resource" "batch_account" { + type = "Microsoft.Batch/batchAccounts@2024-02-01" + name = var.batch_account_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + poolAllocationMode = "UserSubscription" + publicNetworkAccess = "Disabled" + allowedAuthenticationModes = [ + "AAD" + ] + autoStorage = { + storageAccountId = var.storage_account_id + authenticationMode = "BatchAccountManagedIdentity" + } + encryption = { + keySource = "Microsoft.Batch" + } + keyVaultReference = { + id = var.key_vault_id + url = var.key_vault_url + } + networkProfile = { + accountAccess = { + defaultAction = "Deny" + ipRules = [] + } + nodeManagementAccess = { + defaultAction = "Deny" + ipRules = [] + } + } + } + } + } + bicep_pattern: | + resource batchAccount 'Microsoft.Batch/batchAccounts@2024-02-01' = { + name: batchAccountName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + poolAllocationMode: 'UserSubscription' + publicNetworkAccess: 'Disabled' + allowedAuthenticationModes: [ + 'AAD' + ] + autoStorage: { + storageAccountId: storageAccountId + authenticationMode: 'BatchAccountManagedIdentity' + } + encryption: { + keySource: 'Microsoft.Batch' + } + keyVaultReference: { + id: keyVaultId + url: keyVaultUrl + } + networkProfile: { + accountAccess: { + defaultAction: 'Deny' + ipRules: [] + } + nodeManagementAccess: { + defaultAction: 'Deny' + ipRules: [] + } + } + } + } + prohibitions: + - Never use shared key authentication — set allowedAuthenticationModes to AAD only + - Never hardcode storage account keys in auto-storage config — use BatchAccountManagedIdentity + - Never set publicNetworkAccess to Enabled without network profile restrictions + - Never use BatchService pool allocation mode when VNet control is required + - Never embed secrets in task command lines — use Key Vault references +- id: AZ-BATCH-002 + severity: required + description: Deploy Batch pools with VNet injection and no public IP for compute nodes + rationale: Compute nodes with public IPs create attack surface; VNet injection enables network security group control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Batch/batchAccounts +- id: AZ-BATCH-003 + severity: recommended + description: Configure auto-scale formulas for cost optimization + rationale: Static pools waste resources during idle periods; auto-scale adjusts capacity to workload demand + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Batch/batchAccounts +- id: AZ-BATCH-004 + severity: recommended + description: Use container task execution for reproducible and isolated job processing + rationale: Container tasks provide consistent execution environments and faster node startup via pre-fetched images + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Batch/batchAccounts +patterns: +- name: Batch account with user-subscription pools and private networking + description: Batch account with AAD auth, private endpoints, VNet-injected pools, and auto-scale +anti_patterns: +- description: Do not use shared key authentication for Batch + instead: Set allowedAuthenticationModes to AAD only and use managed identity +- description: Do not deploy pools with public IP addresses + instead: Use VNet injection with publicIPAddressConfiguration set to NoPublicIPAddresses +references: +- title: Azure Batch security best practices + url: https://learn.microsoft.com/azure/batch/security-best-practices +- title: Batch account with private endpoints + url: https://learn.microsoft.com/azure/batch/private-connectivity diff --git a/azext_prototype/governance/policies/azure/compute/container-instances.policy.yaml b/azext_prototype/governance/policies/azure/compute/container-instances.policy.yaml new file mode 100644 index 0000000..6c42f65 --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/container-instances.policy.yaml @@ -0,0 +1,218 @@ +kind: policy +domain: azure-compute +description: Governance policies for Container Instances +last_updated: '2026-03-27' +rules: +- id: AZ-ACI-001 + severity: required + description: Deploy Azure Container Instances with managed identity, VNet injection, and no public IP + rationale: ACI containers often run batch or integration tasks; VNet injection prevents public exposure, managed identity + removes credential needs + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.ContainerRegistry/registries@2023-07-01 + name: Container Registry + description: Private container registry for image storage — use managed identity for image pull + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-aci + description: Diagnostic settings to route container logs and events to Log Analytics + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: AcrPull role + description: RBAC role assignment granting ACI managed identity the AcrPull role on the container registry + targets: + - services: + - Microsoft.ContainerInstance/containerGroups + terraform_pattern: | + resource "azapi_resource" "container_group" { + type = "Microsoft.ContainerInstance/containerGroups@2023-05-01" + name = var.container_group_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + osType = "Linux" + restartPolicy = "OnFailure" + ipAddress = { + type = "Private" + ports = [ + { + port = var.container_port + protocol = "TCP" + } + ] + } + subnetIds = [ + { + id = var.subnet_id + name = var.subnet_name + } + ] + containers = [ + { + name = var.container_name + properties = { + image = var.container_image + ports = [ + { + port = var.container_port + protocol = "TCP" + } + ] + resources = { + requests = { + cpu = var.cpu_cores + memoryInGB = var.memory_gb + } + limits = { + cpu = var.cpu_cores + memoryInGB = var.memory_gb + } + } + environmentVariables = [] + } + } + ] + imageRegistryCredentials = [ + { + server = var.acr_login_server + identity = var.acr_identity_id + } + ] + encryptionProperties = { + vaultBaseUrl = var.key_vault_url + keyName = var.encryption_key_name + keyVersion = var.encryption_key_version + } + } + } + } + bicep_pattern: | + resource containerGroup 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = { + name: containerGroupName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + osType: 'Linux' + restartPolicy: 'OnFailure' + ipAddress: { + type: 'Private' + ports: [ + { + port: containerPort + protocol: 'TCP' + } + ] + } + subnetIds: [ + { + id: subnetId + name: subnetName + } + ] + containers: [ + { + name: containerName + properties: { + image: containerImage + ports: [ + { + port: containerPort + protocol: 'TCP' + } + ] + resources: { + requests: { + cpu: cpuCores + memoryInGB: memoryGb + } + limits: { + cpu: cpuCores + memoryInGB: memoryGb + } + } + environmentVariables: [] + } + } + ] + imageRegistryCredentials: [ + { + server: acrLoginServer + identity: acrIdentityId + } + ] + encryptionProperties: { + vaultBaseUrl: keyVaultUrl + keyName: encryptionKeyName + keyVersion: encryptionKeyVersion + } + } + } + prohibitions: + - Never hardcode registry passwords in imageRegistryCredentials — use managed identity + - Never set ipAddress.type to Public for production workloads + - Never pass secrets as plain-text environment variables — use secure environment variables or Key Vault + - Never omit resource limits — always set both requests and limits for cpu and memory + - Never use latest tag for container images — always pin to a specific version or digest +- id: AZ-ACI-002 + severity: required + description: Use secure environment variables or Key Vault references for secrets + rationale: Plain-text environment variables are visible in container group definitions; secure variables are encrypted at + rest + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ContainerInstance/containerGroups +- id: AZ-ACI-003 + severity: recommended + description: Set resource limits and requests on all containers + rationale: Resource limits prevent noisy-neighbor issues and ensure predictable performance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ContainerInstance/containerGroups +- id: AZ-ACI-004 + severity: recommended + description: Pull images from a private registry using managed identity + rationale: Public registry pulls are subject to rate limiting, supply chain attacks, and unavailability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ContainerInstance/containerGroups +patterns: +- name: ACI with VNet injection and managed identity + description: Private container group with VNet integration, managed identity for ACR pull, and encrypted secrets +anti_patterns: +- description: Do not deploy containers with public IP addresses + instead: Use VNet injection with ipAddress.type=Private and subnetIds +- description: Do not use registry passwords for image pull + instead: Use managed identity with AcrPull role assignment on the container registry +references: +- title: Azure Container Instances documentation + url: https://learn.microsoft.com/azure/container-instances/container-instances-overview +- title: ACI VNet deployment + url: https://learn.microsoft.com/azure/container-instances/container-instances-vnet diff --git a/azext_prototype/governance/policies/azure/compute/disk-encryption-set.policy.yaml b/azext_prototype/governance/policies/azure/compute/disk-encryption-set.policy.yaml new file mode 100644 index 0000000..7ee6472 --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/disk-encryption-set.policy.yaml @@ -0,0 +1,213 @@ +kind: policy +domain: azure-compute +description: Governance policies for Disk Encryption Set +last_updated: '2026-03-27' +rules: +- id: AZ-DES-001 + severity: required + description: Create Disk Encryption Set with customer-managed key from Key Vault + rationale: Customer-managed keys (CMK) provide control over encryption keys and meet compliance requirements + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-cmk + description: Key Vault with purge protection enabled for storing CMK encryption keys + - type: Microsoft.KeyVault/vaults/keys@2023-07-01 + name: des-cmk-key + description: RSA 2048-bit or higher encryption key for Disk Encryption Set + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Key Vault Crypto Service Encryption User + description: Grants DES identity permission to use Key Vault encryption keys + targets: + - services: + - Microsoft.Compute/diskEncryptionSets + terraform_pattern: | + resource "azapi_resource" "disk_encryption_set" { + type = "Microsoft.Compute/diskEncryptionSets@2024-03-01" + name = var.des_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + activeKey = { + sourceVault = { + id = var.key_vault_id + } + keyUrl = var.key_url + } + encryptionType = "EncryptionAtRestWithCustomerKey" + rotationToLatestKeyVersionEnabled = true + } + } + } + bicep_pattern: | + resource diskEncryptionSet 'Microsoft.Compute/diskEncryptionSets@2024-03-01' = { + name: desName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + activeKey: { + sourceVault: { + id: keyVaultId + } + keyUrl: keyUrl + } + encryptionType: 'EncryptionAtRestWithCustomerKey' + rotationToLatestKeyVersionEnabled: true + } + } + prohibitions: + - Do not use EncryptionAtRestWithPlatformKey when CMK is required by policy + - Do not disable rotationToLatestKeyVersionEnabled — manual rotation causes outages on key expiry + - Do not use a Key Vault without purge protection — key deletion would make disks inaccessible +- id: AZ-DES-002 + severity: required + description: Grant the Disk Encryption Set identity access to the Key Vault + rationale: Without Key Vault access, the DES cannot retrieve the encryption key and disk operations will fail + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Compute/diskEncryptionSets@2024-03-01 + name: des-cmk + description: Disk Encryption Set with system-assigned identity for Key Vault access + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-cmk + description: Key Vault with RBAC authorization for DES key access + targets: + - services: + - Microsoft.Compute/diskEncryptionSets + terraform_pattern: | + resource "azapi_resource" "des_role_assignment" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.role_assignment_name + parent_id = var.key_vault_id + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/e147488a-f6f5-4113-8e2d-b22465e65bf6" + principalId = azapi_resource.disk_encryption_set.identity[0].principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource desRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVault.id, diskEncryptionSet.id, 'e147488a-f6f5-4113-8e2d-b22465e65bf6') + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'e147488a-f6f5-4113-8e2d-b22465e65bf6') + principalId: diskEncryptionSet.identity.principalId + principalType: 'ServicePrincipal' + } + } + prohibitions: + - Do not use access policies for Key Vault when using RBAC authorization model + - Do not grant Key Vault Administrator to the DES — use least-privilege Crypto Service Encryption User +- id: AZ-DES-003 + severity: required + description: Enable automatic key rotation to latest key version + rationale: Manual key rotation risks service disruption if keys expire; automatic rotation ensures continuity + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Compute/diskEncryptionSets + terraform_pattern: | + # Set rotationToLatestKeyVersionEnabled = true in DES properties + # See DES-001 terraform_pattern for full example + # Use keyUrl WITHOUT version suffix for auto-rotation + bicep_pattern: | + // Set rotationToLatestKeyVersionEnabled: true in DES properties + // See DES-001 bicep_pattern for full example + // Use keyUrl WITHOUT version suffix for auto-rotation + prohibitions: + - Do not pin keyUrl to a specific key version when auto-rotation is enabled + - Do not disable auto-rotation without an explicit key rotation procedure +- id: AZ-DES-004 + severity: recommended + description: Use EncryptionAtRestWithPlatformAndCustomerKeys for double encryption + rationale: Double encryption uses both platform-managed and customer-managed keys for defense in depth + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-cmk + description: Key Vault with purge protection for double-encryption keys + - type: Microsoft.KeyVault/vaults/keys@2023-07-01 + name: des-double-enc-key + description: RSA encryption key for platform-and-customer double encryption + targets: + - services: + - Microsoft.Compute/diskEncryptionSets + terraform_pattern: | + resource "azapi_resource" "des_double_encryption" { + type = "Microsoft.Compute/diskEncryptionSets@2024-03-01" + name = var.des_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + activeKey = { + sourceVault = { + id = var.key_vault_id + } + keyUrl = var.key_url + } + encryptionType = "EncryptionAtRestWithPlatformAndCustomerKeys" + rotationToLatestKeyVersionEnabled = true + } + } + } + bicep_pattern: | + resource desDoubleEncryption 'Microsoft.Compute/diskEncryptionSets@2024-03-01' = { + name: desName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + activeKey: { + sourceVault: { + id: keyVaultId + } + keyUrl: keyUrl + } + encryptionType: 'EncryptionAtRestWithPlatformAndCustomerKeys' + rotationToLatestKeyVersionEnabled: true + } + } + prohibitions: + - Do not use double encryption on ultra-performance workloads without measuring impact +patterns: +- name: Disk Encryption Set with CMK and auto-rotation + description: Customer-managed key encryption with automatic key rotation + example: | + # See DES-001 through DES-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not rely solely on platform-managed encryption when compliance requires CMK + instead: Deploy a Disk Encryption Set with customer-managed keys from Key Vault +- description: Do not store encryption keys in the same Key Vault as application secrets + instead: Use a dedicated Key Vault for disk encryption keys with restricted access +references: +- title: Disk Encryption Sets documentation + url: https://learn.microsoft.com/azure/virtual-machines/disk-encryption +- title: Customer-managed keys for managed disks + url: https://learn.microsoft.com/azure/virtual-machines/disk-encryption-overview diff --git a/azext_prototype/governance/policies/azure/compute/virtual-machines.policy.yaml b/azext_prototype/governance/policies/azure/compute/virtual-machines.policy.yaml new file mode 100644 index 0000000..57947ca --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/virtual-machines.policy.yaml @@ -0,0 +1,368 @@ +kind: policy +domain: azure-compute +description: Governance policies for Virtual Machines +last_updated: '2026-03-27' +rules: +- id: AZ-VM-001 + severity: required + description: Deploy VMs with managed identity, SSH key auth (Linux), and no public IP + rationale: Managed identity eliminates credential management; SSH keys prevent brute-force attacks; no public IP reduces + attack surface + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkInterfaces@2023-04-01 + name: nic-vm + description: Network interface with NSG association and no public IP + - type: Microsoft.Compute/diskEncryptionSets@2024-03-01 + name: des-cmk + description: Disk Encryption Set with customer-managed key for OS and data disks + - type: Microsoft.Network/bastionHosts@2023-04-01 + name: bas-mgmt + description: Bastion host for secure remote VM access without public IPs + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-vm + description: Diagnostic settings for VM guest OS metrics and boot diagnostics + - type: Microsoft.Compute/virtualMachines/extensions@2024-03-01 + name: AzureMonitorLinuxAgent + description: Azure Monitor Agent extension for centralized log and metric collection + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + resource "azapi_resource" "vm" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + zones = [var.availability_zone] + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.computer_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + patchSettings = { + patchMode = "AutomaticByPlatform" + assessmentMode = "AutomaticByPlatform" + automaticByPlatformSettings = { + rebootSetting = "IfRequired" + } + } + } + } + storageProfile = { + imageReference = { + publisher = "Canonical" + offer = "0001-com-ubuntu-server-jammy" + sku = "22_04-lts-gen2" + version = "latest" + } + osDisk = { + name = "${var.vm_name}-osdisk" + createOption = "FromImage" + caching = "ReadWrite" + managedDisk = { + storageAccountType = "Premium_LRS" + diskEncryptionSet = { + id = var.disk_encryption_set_id + } + } + deleteOption = "Delete" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + properties = { + deleteOption = "Delete" + } + } + ] + } + securityProfile = { + encryptionAtHost = true + securityType = "TrustedLaunch" + uefiSettings = { + secureBootEnabled = true + vTpmEnabled = true + } + } + diagnosticsProfile = { + bootDiagnostics = { + enabled = true + } + } + } + } + } + bicep_pattern: | + resource vm 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + identity: { + type: 'SystemAssigned' + } + zones: [availabilityZone] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: computerName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + patchSettings: { + patchMode: 'AutomaticByPlatform' + assessmentMode: 'AutomaticByPlatform' + automaticByPlatformSettings: { + rebootSetting: 'IfRequired' + } + } + } + } + storageProfile: { + imageReference: { + publisher: 'Canonical' + offer: '0001-com-ubuntu-server-jammy' + sku: '22_04-lts-gen2' + version: 'latest' + } + osDisk: { + name: '${vmName}-osdisk' + createOption: 'FromImage' + caching: 'ReadWrite' + managedDisk: { + storageAccountType: 'Premium_LRS' + diskEncryptionSet: { + id: diskEncryptionSetId + } + } + deleteOption: 'Delete' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + properties: { + deleteOption: 'Delete' + } + } + ] + } + securityProfile: { + encryptionAtHost: true + securityType: 'TrustedLaunch' + uefiSettings: { + secureBootEnabled: true + vTpmEnabled: true + } + } + diagnosticsProfile: { + bootDiagnostics: { + enabled: true + } + } + } + } + prohibitions: + - Do not use password authentication for Linux VMs — use SSH keys + - Do not hardcode adminPassword in templates — use Key Vault references + - Do not assign public IPs to VMs — use Bastion for management access + - Do not deploy VMs without managed identity + - Do not use unmanaged disks — always use managed disks +- id: AZ-VM-002 + severity: required + description: Enable Trusted Launch with Secure Boot and vTPM + rationale: Trusted Launch protects against boot-level attacks with measured boot, secure boot, and vTPM + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: [] + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # Set in securityProfile: + # securityType = "TrustedLaunch" + # uefiSettings = { secureBootEnabled = true, vTpmEnabled = true } + # See VM-001 terraform_pattern for full example + bicep_pattern: | + // Set in securityProfile: + // securityType: 'TrustedLaunch' + // uefiSettings: { secureBootEnabled: true, vTpmEnabled: true } + // See VM-001 bicep_pattern for full example + prohibitions: + - Do not disable Secure Boot or vTPM unless specific workload requires it + - Do not use Gen1 images with Trusted Launch — requires Gen2 images +- id: AZ-VM-003 + severity: required + description: Enable encryption at host and use Disk Encryption Sets for CMK + rationale: Encryption at host ensures temp disks and caches are encrypted; CMK provides key control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.Compute/diskEncryptionSets@2024-03-01 + name: des-cmk + description: Disk Encryption Set with customer-managed key for VM disk encryption + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-cmk + description: Key Vault storing encryption keys for Disk Encryption Set + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # Set securityProfile.encryptionAtHost = true + # Set osDisk.managedDisk.diskEncryptionSet.id to DES resource ID + # See VM-001 terraform_pattern for full example + bicep_pattern: | + // Set securityProfile.encryptionAtHost: true + // Set osDisk.managedDisk.diskEncryptionSet.id to DES resource ID + // See VM-001 bicep_pattern for full example + prohibitions: + - Do not rely solely on platform-managed encryption when compliance requires CMK +- id: AZ-VM-004 + severity: recommended + description: Install Azure Monitor Agent and configure data collection rules + rationale: Azure Monitor Agent replaces the legacy Log Analytics agent and enables centralized log collection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/dataCollectionRules@2023-03-11 + name: dcr-vm-logs + description: Data collection rule defining which logs and metrics to collect from VMs + - type: Microsoft.Insights/dataCollectionRuleAssociations@2023-03-11 + name: dcra-vm + description: Association linking the data collection rule to the VM + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as the destination for VM telemetry + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + resource "azapi_resource" "ama_extension" { + type = "Microsoft.Compute/virtualMachines/extensions@2024-03-01" + name = "AzureMonitorLinuxAgent" + location = var.location + parent_id = azapi_resource.vm.id + body = { + properties = { + publisher = "Microsoft.Azure.Monitor" + type = "AzureMonitorLinuxAgent" + typeHandlerVersion = "1.0" + autoUpgradeMinorVersion = true + enableAutomaticUpgrade = true + settings = { + authentication = { + managedIdentity = { + identifier-name = "mi_res_id" + identifier-value = azapi_resource.vm.id + } + } + } + } + } + } + bicep_pattern: | + resource amaExtension 'Microsoft.Compute/virtualMachines/extensions@2024-03-01' = { + parent: vm + name: 'AzureMonitorLinuxAgent' + location: location + properties: { + publisher: 'Microsoft.Azure.Monitor' + type: 'AzureMonitorLinuxAgent' + typeHandlerVersion: '1.0' + autoUpgradeMinorVersion: true + enableAutomaticUpgrade: true + settings: { + authentication: { + managedIdentity: { + 'identifier-name': 'mi_res_id' + 'identifier-value': vm.id + } + } + } + } + } + prohibitions: + - Do not use the legacy Microsoft Monitoring Agent (MMA) — it is deprecated +- id: AZ-VM-005 + severity: recommended + description: Enable automatic OS patching with AutomaticByPlatform mode + rationale: Automatic patching ensures VMs receive security updates without manual intervention + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # Set patchSettings in osProfile.linuxConfiguration: + # patchMode = "AutomaticByPlatform" + # assessmentMode = "AutomaticByPlatform" + # See VM-001 terraform_pattern for full example + bicep_pattern: | + // Set patchSettings in osProfile.linuxConfiguration: + // patchMode: 'AutomaticByPlatform' + // assessmentMode: 'AutomaticByPlatform' + // See VM-001 bicep_pattern for full example + prohibitions: + - Do not use Manual patch mode without an explicit patching procedure +patterns: +- name: Production VM with full security baseline + description: Linux VM with Trusted Launch, CMK encryption, managed identity, and monitoring + example: | + # See VM-001 through VM-005 for complete azapi_resource patterns +anti_patterns: +- description: Do not use password authentication for Linux VMs + instead: 'Use SSH key authentication with disablePasswordAuthentication: true' +- description: Do not assign public IPs directly to VMs + instead: Use Azure Bastion for management and internal load balancers for application access +- description: Do not deploy VMs without encryption at host + instead: 'Enable encryptionAtHost: true in the security profile' +references: +- title: Virtual machines documentation + url: https://learn.microsoft.com/azure/virtual-machines/overview +- title: Trusted Launch for VMs + url: https://learn.microsoft.com/azure/virtual-machines/trusted-launch +- title: Azure Monitor Agent + url: https://learn.microsoft.com/azure/azure-monitor/agents/azure-monitor-agent-overview diff --git a/azext_prototype/governance/policies/azure/compute/vmss.policy.yaml b/azext_prototype/governance/policies/azure/compute/vmss.policy.yaml new file mode 100644 index 0000000..b4b9d76 --- /dev/null +++ b/azext_prototype/governance/policies/azure/compute/vmss.policy.yaml @@ -0,0 +1,413 @@ +kind: policy +domain: azure-compute +description: Governance policies for Vmss +last_updated: '2026-03-27' +rules: +- id: AZ-VMSS-001 + severity: required + description: Deploy VMSS with Flexible orchestration mode, managed identity, and zone distribution + rationale: Flexible mode is the recommended orchestration; Uniform is legacy. Managed identity eliminates credential management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-vmss + description: Network security group applied to VMSS network interface configurations + - type: Microsoft.Network/loadBalancers@2023-04-01 + name: lb-vmss + description: Standard load balancer for distributing traffic across VMSS instances + - type: Microsoft.Compute/diskEncryptionSets@2024-03-01 + name: des-cmk + description: Disk Encryption Set with customer-managed key for VMSS OS and data disks + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-vmss + description: Diagnostic settings for VMSS instance metrics and boot diagnostics + - type: Microsoft.Insights/autoscaleSettings@2022-10-01 + name: autoscale-vmss + description: Autoscale rules for CPU-based scale-out and scale-in of VMSS instances + targets: + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 + singlePlacementGroup = false + virtualMachineProfile = { + osProfile = { + computerNamePrefix = var.name_prefix + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + imageReference = { + publisher = "Canonical" + offer = "0001-com-ubuntu-server-jammy" + sku = "22_04-lts-gen2" + version = "latest" + } + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" + diskEncryptionSet = { + id = var.disk_encryption_set_id + } + } + } + } + networkProfile = { + networkInterfaceConfigurations = [ + { + name = "nic-config" + properties = { + primary = true + enableAcceleratedNetworking = true + networkSecurityGroup = { + id = var.nsg_id + } + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + primary = true + subnet = { + id = var.subnet_id + } + } + } + ] + } + } + ] + } + securityProfile = { + encryptionAtHost = true + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT30M" + } + } + } + } + bicep_pattern: | + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + virtualMachineProfile: { + osProfile: { + computerNamePrefix: namePrefix + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + imageReference: { + publisher: 'Canonical' + offer: '0001-com-ubuntu-server-jammy' + sku: '22_04-lts-gen2' + version: 'latest' + } + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + diskEncryptionSet: { + id: diskEncryptionSetId + } + } + } + } + networkProfile: { + networkInterfaceConfigurations: [ + { + name: 'nic-config' + properties: { + primary: true + enableAcceleratedNetworking: true + networkSecurityGroup: { + id: nsgId + } + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + primary: true + subnet: { + id: subnetId + } + } + } + ] + } + } + ] + } + securityProfile: { + encryptionAtHost: true + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT30M' + } + } + } + prohibitions: + - Do not use Uniform orchestration mode for new deployments — Flexible is recommended + - Do not use password authentication for Linux — use SSH keys + - Do not hardcode adminPassword in templates — use Key Vault references + - Do not deploy VMSS without NSG on network interfaces + - Do not assign public IPs to VMSS instances — use internal LB and Bastion +- id: AZ-VMSS-002 + severity: required + description: Enable encryption at host for VMSS instances + rationale: Encryption at host ensures temp disks, caches, and data-in-transit to storage are encrypted + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: [] + targets: + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # Set securityProfile.encryptionAtHost = true in virtualMachineProfile + # See VMSS-001 terraform_pattern for full example + bicep_pattern: | + // Set securityProfile.encryptionAtHost: true in virtualMachineProfile + // See VMSS-001 bicep_pattern for full example + prohibitions: + - Do not disable encryption at host — temp disks and caches would be unencrypted +- id: AZ-VMSS-003 + severity: required + description: Configure autoscale rules based on relevant metrics + rationale: Without autoscale, VMSS requires manual capacity management and cannot respond to load changes + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Compute/virtualMachineScaleSets@2024-03-01 + name: vmss-target + description: Target VMSS that autoscale settings apply to + targets: + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + resource "azapi_resource" "vmss_autoscale" { + type = "Microsoft.Insights/autoscaleSettings@2022-10-01" + name = var.autoscale_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + enabled = true + targetResourceUri = azapi_resource.vmss.id + profiles = [ + { + name = "default" + capacity = { + minimum = tostring(var.min_instances) + maximum = tostring(var.max_instances) + default = tostring(var.default_instances) + } + rules = [ + { + metricTrigger = { + metricName = "Percentage CPU" + metricResourceUri = azapi_resource.vmss.id + timeGrain = "PT1M" + statistic = "Average" + timeWindow = "PT5M" + timeAggregation = "Average" + operator = "GreaterThan" + threshold = 75 + } + scaleAction = { + direction = "Increase" + type = "ChangeCount" + value = "1" + cooldown = "PT5M" + } + }, + { + metricTrigger = { + metricName = "Percentage CPU" + metricResourceUri = azapi_resource.vmss.id + timeGrain = "PT1M" + statistic = "Average" + timeWindow = "PT5M" + timeAggregation = "Average" + operator = "LessThan" + threshold = 25 + } + scaleAction = { + direction = "Decrease" + type = "ChangeCount" + value = "1" + cooldown = "PT5M" + } + } + ] + } + ] + } + } + } + bicep_pattern: | + resource vmssAutoscale 'Microsoft.Insights/autoscaleSettings@2022-10-01' = { + name: autoscaleName + location: location + properties: { + enabled: true + targetResourceUri: vmss.id + profiles: [ + { + name: 'default' + capacity: { + minimum: string(minInstances) + maximum: string(maxInstances) + default: string(defaultInstances) + } + rules: [ + { + metricTrigger: { + metricName: 'Percentage CPU' + metricResourceUri: vmss.id + timeGrain: 'PT1M' + statistic: 'Average' + timeWindow: 'PT5M' + timeAggregation: 'Average' + operator: 'GreaterThan' + threshold: 75 + } + scaleAction: { + direction: 'Increase' + type: 'ChangeCount' + value: '1' + cooldown: 'PT5M' + } + } + { + metricTrigger: { + metricName: 'Percentage CPU' + metricResourceUri: vmss.id + timeGrain: 'PT1M' + statistic: 'Average' + timeWindow: 'PT5M' + timeAggregation: 'Average' + operator: 'LessThan' + threshold: 25 + } + scaleAction: { + direction: 'Decrease' + type: 'ChangeCount' + value: '1' + cooldown: 'PT5M' + } + } + ] + } + ] + } + } + prohibitions: + - Do not set minimum capacity to 0 in production — leaves no instances for traffic + - Do not use only scale-out rules without scale-in — costs will grow unbounded +- id: AZ-VMSS-004 + severity: recommended + description: Enable automatic OS upgrades and automatic instance repairs + rationale: Automatic upgrades keep instances patched; automatic repairs replace unhealthy instances + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/loadBalancers/probes@2023-04-01 + name: health-probe + description: Load balancer health probe providing health signal for automatic instance repairs + targets: + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # Add to VMSS properties: + # automaticRepairsPolicy = { enabled = true, gracePeriod = "PT30M" } + # See VMSS-001 terraform_pattern for automaticRepairsPolicy + # For automatic OS upgrades, add upgradePolicy: + # upgradePolicy = { mode = "Automatic" } + bicep_pattern: | + // Add to VMSS properties: + // automaticRepairsPolicy: { enabled: true, gracePeriod: 'PT30M' } + // See VMSS-001 bicep_pattern for automaticRepairsPolicy + // For automatic OS upgrades, add upgradePolicy: + // upgradePolicy: { mode: 'Automatic' } + prohibitions: + - Do not enable automatic repairs without a health probe — repairs need health signal +patterns: +- name: VMSS Flexible with autoscale and encryption + description: Zone-redundant VMSS with Flexible orchestration, CMK encryption, and autoscale + example: | + # See VMSS-001 through VMSS-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use Uniform orchestration for new VMSS deployments + instead: Use Flexible orchestration mode for better availability and flexibility +- description: Do not use password authentication for Linux VMSS instances + instead: 'Use SSH key authentication with disablePasswordAuthentication: true' +references: +- title: VMSS documentation + url: https://learn.microsoft.com/azure/virtual-machine-scale-sets/overview +- title: Flexible orchestration mode + url: https://learn.microsoft.com/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-orchestration-modes diff --git a/azext_prototype/governance/policies/azure/container-apps.policy.yaml b/azext_prototype/governance/policies/azure/container-apps.policy.yaml deleted file mode 100644 index f2b900f..0000000 --- a/azext_prototype/governance/policies/azure/container-apps.policy.yaml +++ /dev/null @@ -1,73 +0,0 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: container-apps - category: azure - services: [container-apps, container-registry] - last_reviewed: "2025-12-01" - -rules: - - id: CA-001 - severity: required - description: "Use managed identity for all service-to-service auth" - rationale: "Eliminates credential rotation burden and secret sprawl" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [container-apps, container-registry] - require_config: [identity] - error_message: "Service '{service_name}' ({service_type}) missing managed identity configuration" - - - id: CA-002 - severity: required - description: "Deploy Container Apps in a VNET-integrated environment" - rationale: "Network isolation is mandatory for internal workloads" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - when_services_present: [container-apps] - require_service: [virtual-network] - error_message: "Template with container-apps must include a virtual-network service for VNET integration" - - - id: CA-003 - severity: recommended - description: "Use consumption plan for dev/test, dedicated for production" - rationale: "Cost optimization without sacrificing prod reliability" - applies_to: [cloud-architect, cost-analyst, biz-analyst] - - - id: CA-004 - severity: recommended - description: "Set min replicas to 0 for non-critical services in dev" - rationale: "Avoids unnecessary spend during idle periods" - applies_to: [terraform-agent, bicep-agent, cost-analyst] - -patterns: - - name: "Container App with Key Vault references" - description: "Use Key Vault references for secrets instead of environment variables" - example: | - secrets: - - name: db-connection - keyVaultUrl: https://{kv-name}.vault.azure.net/secrets/db-connection - identity: system - - - name: "Health probes" - description: "Always configure liveness and readiness probes" - example: | - probes: - - type: liveness - httpGet: - path: /healthz - port: 8080 - initialDelaySeconds: 5 - periodSeconds: 10 - -anti_patterns: - - description: "Do not store secrets in environment variables or app settings" - instead: "Use Key Vault references with managed identity" - - description: "Do not use admin credentials for container registry" - instead: "Use managed identity with AcrPull role assignment" - -references: - - title: "Container Apps landing zone accelerator" - url: "https://learn.microsoft.com/azure/container-apps/landing-zone-accelerator" - - title: "Container Apps networking" - url: "https://learn.microsoft.com/azure/container-apps/networking" diff --git a/azext_prototype/governance/policies/azure/cosmos-db.policy.yaml b/azext_prototype/governance/policies/azure/cosmos-db.policy.yaml deleted file mode 100644 index 87c0285..0000000 --- a/azext_prototype/governance/policies/azure/cosmos-db.policy.yaml +++ /dev/null @@ -1,68 +0,0 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: cosmos-db - category: azure - services: [cosmos-db] - last_reviewed: "2025-12-01" - -rules: - - id: CDB-001 - severity: required - description: "Use Microsoft Entra RBAC for data-plane access" - rationale: "Key-based auth should be disabled where possible" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [cosmos-db] - require_config: [entra_rbac, local_auth_disabled] - error_message: "Service '{service_name}' ({service_type}) missing {config_key}: true" - - - id: CDB-002 - severity: recommended - description: "Configure appropriate consistency level (not Strong unless required)" - rationale: "Strong consistency has significant latency and cost implications" - applies_to: [cloud-architect, app-developer, biz-analyst] - template_check: - scope: [cosmos-db] - reject_config_value: - consistency: strong - error_message: "Service '{service_name}' ({service_type}) uses 'strong' consistency — consider session or eventual unless strong is justified" - - - id: CDB-003 - severity: recommended - description: "Use autoscale throughput for variable workloads" - rationale: "Avoids over-provisioning while handling traffic spikes" - applies_to: [cloud-architect, terraform-agent, bicep-agent, cost-analyst] - template_check: - scope: [cosmos-db] - require_config: [autoscale] - error_message: "Service '{service_name}' ({service_type}) missing autoscale: true for throughput scaling" - - - id: CDB-004 - severity: recommended - description: "Design partition keys based on query patterns, not just cardinality" - rationale: "Poor partition keys cause hot partitions and throttling" - applies_to: [cloud-architect, app-developer, biz-analyst] - template_check: - scope: [cosmos-db] - require_config: [partition_key] - error_message: "Service '{service_name}' ({service_type}) missing partition_key definition" - -patterns: - - name: "Cosmos DB with RBAC" - description: "Disable key-based auth and use Entra RBAC" - example: | - resource "azurerm_cosmosdb_account" "main" { - local_authentication_disabled = true - } - -anti_patterns: - - description: "Do not use account-level keys for application access" - instead: "Use Microsoft Entra RBAC with managed identity" - - description: "Do not use unlimited containers without TTL policy" - instead: "Set TTL on containers with transient data" - -references: - - title: "Cosmos DB security baseline" - url: "https://learn.microsoft.com/azure/cosmos-db/security-baseline" diff --git a/azext_prototype/governance/policies/azure/data/__init__.py b/azext_prototype/governance/policies/azure/data/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/data/azure-sql.policy.yaml b/azext_prototype/governance/policies/azure/data/azure-sql.policy.yaml new file mode 100644 index 0000000..d280394 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/azure-sql.policy.yaml @@ -0,0 +1,615 @@ +kind: policy +domain: azure-data +description: Governance policies for Azure Sql +last_updated: '2026-03-27' +rules: +- id: AZ-SQL-001 + severity: required + description: Create SQL Server with AAD-only authentication via separate child resources + rationale: Centralised identity management via Entra ID; SQL auth passwords are a security liability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + scope: + - sql-database + require_config: + - entra_auth_only + error_message: 'Service ''{service_name}'' ({service_type}) missing entra_auth_only: true' + targets: + - services: + - Microsoft.Sql/servers + terraform_pattern: | + resource "azapi_resource" "sql_server" { + type = "Microsoft.Sql/servers@2023-08-01-preview" + name = var.sql_server_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + version = "12.0" + minimalTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + } + } + } + + resource "azapi_resource" "sql_server_aad_admin" { + type = "Microsoft.Sql/servers/administrators@2023-08-01-preview" + name = "ActiveDirectory" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + administratorType = "ActiveDirectory" + login = var.sql_admin_group_name + sid = var.sql_admin_group_object_id + tenantId = var.tenant_id + } + } + } + + resource "azapi_resource" "sql_server_aad_only_auth" { + type = "Microsoft.Sql/servers/azureADOnlyAuthentications@2023-08-01-preview" + name = "Default" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + azureADOnlyAuthentication = true + } + } + + depends_on = [azapi_resource.sql_server_aad_admin] + } + bicep_pattern: | + resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = { + name: sqlServerName + location: location + properties: { + version: '12.0' + minimalTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + } + } + + resource sqlServerAdAdmin 'Microsoft.Sql/servers/administrators@2023-08-01-preview' = { + parent: sqlServer + name: 'ActiveDirectory' + properties: { + administratorType: 'ActiveDirectory' + login: sqlAdminGroupName + sid: sqlAdminGroupObjectId + tenantId: tenant().tenantId + } + } + + resource sqlServerAadOnlyAuth 'Microsoft.Sql/servers/azureADOnlyAuthentications@2023-08-01-preview' = { + parent: sqlServer + name: 'Default' + properties: { + azureADOnlyAuthentication: true + } + dependsOn: [ + sqlServerAdAdmin + ] + } + prohibitions: + - NEVER put administrators or azureADOnlyAuthentications inline in the server body — they MUST be separate child resources + - NEVER set administratorLogin or administratorLoginPassword on the server — these enable SQL auth + - NEVER use SQL DB Contributor role for data access — use T-SQL contained users (CREATE USER [app-identity] FROM EXTERNAL + PROVIDER) + - NEVER use uuid() for role assignment names — use uuidv5() with deterministic seeds derived from resource IDs +- id: AZ-SQL-002 + severity: required + description: Create SQL Database with appropriate SKU and settings + rationale: Databases must be created as child resources of the server with explicit SKU configuration + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5_1" + tier = "GeneralPurpose" + } + properties = { + collation = "SQL_Latin1_General_CP1_CI_AS" + maxSizeBytes = 34359738368 + autoPauseDelay = 60 + minCapacity = 0.5 + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" + } + } + } + bicep_pattern: | + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5_1' + tier: 'GeneralPurpose' + } + properties: { + collation: 'SQL_Latin1_General_CP1_CI_AS' + maxSizeBytes: 34359738368 + autoPauseDelay: 60 + minCapacity: json('0.5') + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } +- id: AZ-SQL-003 + severity: required + description: Enable Transparent Data Encryption (TDE) on every database + rationale: Data-at-rest encryption is a baseline security requirement + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + scope: + - sql-database + require_config: + - tde_enabled + error_message: 'Service ''{service_name}'' ({service_type}) missing tde_enabled: true' + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + resource "azapi_resource" "sql_tde" { + type = "Microsoft.Sql/servers/databases/transparentDataEncryption@2023-08-01-preview" + name = "current" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + state = "Enabled" + } + } + } + bicep_pattern: | + resource sqlTde 'Microsoft.Sql/servers/databases/transparentDataEncryption@2023-08-01-preview' = { + parent: sqlDatabase + name: 'current' + properties: { + state: 'Enabled' + } + } +- id: AZ-SQL-004 + severity: required + description: Enable Advanced Threat Protection on the SQL Server + rationale: Detects anomalous database activities indicating potential security threats + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + scope: + - sql-database + require_config: + - threat_protection + error_message: 'Service ''{service_name}'' ({service_type}) missing threat_protection: true' + targets: + - services: + - Microsoft.Sql/servers + terraform_pattern: | + resource "azapi_resource" "sql_threat_protection" { + type = "Microsoft.Sql/servers/advancedThreatProtectionSettings@2023-08-01-preview" + name = "Default" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + state = "Enabled" + } + } + } + bicep_pattern: | + resource sqlThreatProtection 'Microsoft.Sql/servers/advancedThreatProtectionSettings@2023-08-01-preview' = { + parent: sqlServer + name: 'Default' + properties: { + state: 'Enabled' + } + } +- id: AZ-SQL-005 + severity: required + description: Disable public network access and enforce TLS 1.2 minimum + rationale: Prevents direct internet access; all connections must traverse private endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-sql + description: Private endpoint for SQL Server — required when publicNetworkAccess is Disabled + terraform_pattern: | + resource "azapi_resource" "sql_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.sql_server_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.sql_server_name}" + properties = { + privateLinkServiceId = azapi_resource.sql_server.id + groupIds = ["sqlServer"] + } + } + ] + } + } + } + bicep_pattern: | + resource sqlPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${sqlServerName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${sqlServerName}' + properties: { + privateLinkServiceId: sqlServer.id + groupIds: [ + 'sqlServer' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01 + name: privatelink.database.windows.net + description: Private DNS zone for SQL Server private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "sql_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.database.windows.net" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "sql_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.sql_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "sql_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.sql_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-database-windows-net" + properties = { + privateDnsZoneId = azapi_resource.sql_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource sqlDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.database.windows.net' + location: 'global' + } + + resource sqlDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: sqlDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource sqlPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: sqlPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-database-windows-net' + properties: { + privateDnsZoneId: sqlDnsZone.id + } + } + ] + } + } + targets: + - services: + - Microsoft.Sql/servers + prohibitions: + - NEVER set publicNetworkAccess to Enabled + - NEVER create firewall rules allowing 0.0.0.0-255.255.255.255 + - NEVER set minimalTlsVersion below 1.2 +- id: AZ-SQL-006 + severity: required + description: Enable diagnostic settings to Log Analytics workspace + rationale: Audit trail for access, query performance, and security events + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-sql + description: Diagnostic settings for SQL Database to Log Analytics + terraform_pattern: | + resource "azapi_resource" "sql_db_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.sql_database_name}" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource sqlDbDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: sqlDatabase + name: 'diag-${sqlDatabaseName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Sql/servers/databases +- id: AZ-SQL-007 + severity: recommended + description: Use serverless tier (GP_S_Gen5) for POC and dev/test workloads + rationale: Auto-pause reduces costs for intermittent usage patterns + applies_to: + - cloud-architect + - cost-analyst + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers/databases +- id: AZ-SQL-008 + severity: required + description: Enable SQL Database auditing on the logical server + rationale: 'WAF Security: Auditing tracks database events and writes them to an audit log, maintaining regulatory compliance + and providing insight into database activity' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Sql/servers + terraform_pattern: | + resource "azapi_resource" "sql_server_auditing" { + type = "Microsoft.Sql/servers/auditingSettings@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + state = "Enabled" + isAzureMonitorTargetEnabled = true + retentionDays = 90 + } + } + } + bicep_pattern: | + resource sqlServerAuditing 'Microsoft.Sql/servers/auditingSettings@2023-08-01-preview' = { + parent: sqlServer + name: 'default' + properties: { + state: 'Enabled' + isAzureMonitorTargetEnabled: true + retentionDays: 90 + } + } +- id: AZ-SQL-009 + severity: recommended + description: Enable SQL Vulnerability Assessment on the SQL Server + rationale: 'WAF Security: Built-in service that identifies, tracks, and helps remediate potential database vulnerabilities + with actionable remediation scripts' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Sql/servers + terraform_pattern: | + resource "azapi_resource" "sql_vulnerability_assessment" { + type = "Microsoft.Sql/servers/sqlVulnerabilityAssessments@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + state = "Enabled" + } + } + } + bicep_pattern: | + resource sqlVulnerabilityAssessment 'Microsoft.Sql/servers/sqlVulnerabilityAssessments@2023-08-01-preview' = { + parent: sqlServer + name: 'default' + properties: { + state: 'Enabled' + } + } +- id: AZ-SQL-010 + severity: recommended + description: Configure zone redundancy for Business Critical or Premium tier databases + rationale: 'WAF Reliability: Zone-redundant availability distributes compute and storage across availability zones, maintaining + operations during zone failures' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers/databases + prohibitions: + - NEVER disable zone redundancy on Business Critical tier databases in production +- id: AZ-SQL-011 + severity: recommended + description: Use failover groups for automatic geo-failover of critical databases + rationale: 'WAF Reliability: Failover groups automate failover from primary to secondary with read-write and read-only listener + endpoints that remain unchanged during geo-failovers' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers + terraform_pattern: | + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" + } + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + bicep_pattern: | + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServer + name: failoverGroupName + properties: { + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + databases: [ + sqlDatabase.id + ] + } + } +patterns: +- name: SQL Server with AAD-only auth and private endpoint + description: Complete SQL Server deployment with Entra-only authentication, TDE, threat protection, private endpoint, and + diagnostics +anti_patterns: +- description: Do not use SQL authentication with username/password + instead: Use Microsoft Entra (Azure AD) authentication with managed identity +- description: Do not set firewall rule 0.0.0.0-255.255.255.255 + instead: Use private endpoints for all connectivity +- description: Do not put administrators inline in the server body + instead: Create Microsoft.Sql/servers/administrators and Microsoft.Sql/servers/azureADOnlyAuthentications as separate child + resources +- description: Do not use SQL DB Contributor role for application data access + instead: 'Use T-SQL contained users: CREATE USER [app-identity] FROM EXTERNAL PROVIDER' +references: +- title: SQL Database security best practices + url: https://learn.microsoft.com/azure/azure-sql/database/security-best-practice +- title: Azure SQL private endpoints + url: https://learn.microsoft.com/azure/azure-sql/database/private-endpoint-overview +- title: AAD-only authentication + url: https://learn.microsoft.com/azure/azure-sql/database/authentication-azure-ad-only-authentication +- title: 'WAF: Azure SQL Database service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-sql-database +- title: SQL Database auditing + url: https://learn.microsoft.com/azure/azure-sql/database/auditing-overview +- title: SQL vulnerability assessment + url: https://learn.microsoft.com/azure/azure-sql/database/sql-vulnerability-assessment +- title: SQL Database failover groups + url: https://learn.microsoft.com/azure/azure-sql/database/auto-failover-group-overview diff --git a/azext_prototype/governance/policies/azure/data/backup-vault.policy.yaml b/azext_prototype/governance/policies/azure/data/backup-vault.policy.yaml new file mode 100644 index 0000000..9c63a55 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/backup-vault.policy.yaml @@ -0,0 +1,310 @@ +kind: policy +domain: azure-data +description: Governance policies for Backup Vault +last_updated: '2026-03-27' +rules: +- id: AZ-BKV-001 + severity: required + description: Deploy Backup Vault with geo-redundant storage, immutability, and soft delete enabled + rationale: GRS protects against regional outages; immutability prevents backup tampering; soft delete allows recovery + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01 + name: daily-retention-policy + description: Backup policy defining retention schedule and RPO for protected resources + - type: Microsoft.DataProtection/backupVaults/backupInstances@2024-04-01 + name: backup-instance + description: Backup instance linking a protected resource to the vault and policy + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Backup Contributor + description: Grants Backup Vault identity permission to access source resources for backup + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-backup-vault + description: Diagnostic settings routing backup job and policy logs to Log Analytics + targets: + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + resource "azapi_resource" "backup_vault" { + type = "Microsoft.DataProtection/backupVaults@2024-04-01" + name = var.backup_vault_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + storageSettings = [ + { + datastoreType = "VaultStore" + type = "GeoRedundant" + } + ] + securitySettings = { + softDeleteSettings = { + state = "On" + retentionDurationInDays = 14 + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + bicep_pattern: | + resource backupVault 'Microsoft.DataProtection/backupVaults@2024-04-01' = { + name: backupVaultName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + storageSettings: [ + { + datastoreType: 'VaultStore' + type: 'GeoRedundant' + } + ] + securitySettings: { + softDeleteSettings: { + state: 'On' + retentionDurationInDays: 14 + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + prohibitions: + - Do not use LocallyRedundant storage for production backups — data loss on regional failure + - Do not disable soft delete — backups cannot be recovered after accidental deletion + - Do not set immutability state to Disabled without explicit business justification +- id: AZ-BKV-002 + severity: required + description: Create backup policies with appropriate retention and schedule + rationale: Backup policies define RPO and retention — they must match business recovery requirements + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.DataProtection/backupVaults@2024-04-01 + name: backup-vault + description: Parent Backup Vault that owns this backup policy + targets: + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + resource "azapi_resource" "backup_policy" { + type = "Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01" + name = var.policy_name + parent_id = azapi_resource.backup_vault.id + body = { + properties = { + datasourceTypes = [var.datasource_type] + objectType = "BackupPolicy" + policyRules = [ + { + name = "BackupDaily" + objectType = "AzureBackupRule" + backupParameters = { + objectType = "AzureBackupParams" + backupType = "Incremental" + } + trigger = { + objectType = "ScheduleBasedTriggerContext" + schedule = { + repeatingTimeIntervals = ["R/2024-01-01T02:00:00+00:00/P1D"] + } + taggingCriteria = [ + { + tagInfo = { + tagName = "Default" + } + taggingPriority = 99 + isDefault = true + } + ] + } + dataStore = { + datastoreType = "VaultStore" + objectType = "DataStoreInfoBase" + } + }, + { + name = "RetainDaily" + objectType = "AzureRetentionRule" + isDefault = true + lifecycles = [ + { + deleteAfter = { + objectType = "AbsoluteDeleteOption" + duration = "P30D" + } + sourceDataStore = { + datastoreType = "VaultStore" + objectType = "DataStoreInfoBase" + } + } + ] + } + ] + } + } + } + bicep_pattern: | + resource backupPolicy 'Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01' = { + parent: backupVault + name: policyName + properties: { + datasourceTypes: [datasourceType] + objectType: 'BackupPolicy' + policyRules: [ + { + name: 'BackupDaily' + objectType: 'AzureBackupRule' + backupParameters: { + objectType: 'AzureBackupParams' + backupType: 'Incremental' + } + trigger: { + objectType: 'ScheduleBasedTriggerContext' + schedule: { + repeatingTimeIntervals: ['R/2024-01-01T02:00:00+00:00/P1D'] + } + taggingCriteria: [ + { + tagInfo: { + tagName: 'Default' + } + taggingPriority: 99 + isDefault: true + } + ] + } + dataStore: { + datastoreType: 'VaultStore' + objectType: 'DataStoreInfoBase' + } + } + { + name: 'RetainDaily' + objectType: 'AzureRetentionRule' + isDefault: true + lifecycles: [ + { + deleteAfter: { + objectType: 'AbsoluteDeleteOption' + duration: 'P30D' + } + sourceDataStore: { + datastoreType: 'VaultStore' + objectType: 'DataStoreInfoBase' + } + } + ] + } + ] + } + } + prohibitions: + - Do not set retention below 7 days for production backups + - Do not use full backup type when incremental is available — it wastes storage +- id: AZ-BKV-003 + severity: recommended + description: Enable diagnostic settings for Backup Vault operations + rationale: Monitor backup job success/failure rates and restore operations + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Backup Vault diagnostic logs + targets: + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + resource "azapi_resource" "bkv_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-backup-vault" + parent_id = azapi_resource.backup_vault.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "CoreAzureBackup" + enabled = true + }, + { + category = "AddonAzureBackupJobs" + enabled = true + }, + { + category = "AddonAzureBackupPolicy" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource bkvDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-backup-vault' + scope: backupVault + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'CoreAzureBackup' + enabled: true + } + { + category: 'AddonAzureBackupJobs' + enabled: true + } + { + category: 'AddonAzureBackupPolicy' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit AddonAzureBackupJobs logs — they track backup success and failure +patterns: +- name: Backup Vault with GRS, immutability, and daily policy + description: Production Backup Vault with geo-redundancy, soft delete, and daily incremental backups + example: | + # See BKV-001 through BKV-003 for complete azapi_resource patterns +anti_patterns: +- description: Do not use locally redundant storage for production backup vaults + instead: Use GeoRedundant storage for cross-region protection +- description: Do not disable soft delete on backup vaults + instead: Keep soft delete enabled with at least 14 days retention +references: +- title: Backup Vault documentation + url: https://learn.microsoft.com/azure/backup/backup-vault-overview +- title: Backup Vault immutability + url: https://learn.microsoft.com/azure/backup/backup-azure-immutable-vault-concept diff --git a/azext_prototype/governance/policies/azure/data/cosmos-db.policy.yaml b/azext_prototype/governance/policies/azure/data/cosmos-db.policy.yaml new file mode 100644 index 0000000..32b1227 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/cosmos-db.policy.yaml @@ -0,0 +1,516 @@ +kind: policy +domain: azure-data +description: Governance policies for Cosmos Db +last_updated: '2026-03-27' +rules: +- id: AZ-CDB-001 + severity: required + description: Create Cosmos DB account with Entra RBAC and local auth disabled + rationale: Key-based auth grants full account access and cannot be scoped; Entra RBAC provides fine-grained control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15 + name: Cosmos DB Built-in Data Contributor + description: RBAC role assignment granting Cosmos DB Built-in Data Contributor to the application identity + terraform_pattern: | + resource "azapi_resource" "cosmos_role_assignment" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15" + name = var.cosmos_role_assignment_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + roleDefinitionId = "${azapi_resource.cosmos_account.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002" + principalId = var.app_identity_principal_id + scope = azapi_resource.cosmos_account.id + } + } + } + bicep_pattern: | + resource cosmosRoleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = { + parent: cosmosAccount + name: cosmosRoleAssignmentName + properties: { + roleDefinitionId: '${cosmosAccount.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002' + principalId: appIdentityPrincipalId + scope: cosmosAccount.id + } + } + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-cosmos + description: Private endpoint for Cosmos DB — required when publicNetworkAccess is Disabled + terraform_pattern: | + resource "azapi_resource" "cosmos_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.cosmos_account_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.cosmos_account_name}" + properties = { + privateLinkServiceId = azapi_resource.cosmos_account.id + groupIds = ["Sql"] + } + } + ] + } + } + } + bicep_pattern: | + resource cosmosPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${cosmosAccountName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${cosmosAccountName}' + properties: { + privateLinkServiceId: cosmosAccount.id + groupIds: [ + 'Sql' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.documents.azure.com + description: Private DNS zone for Cosmos DB private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "cosmos_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.documents.azure.com" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "cosmos_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.cosmos_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "cosmos_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.cosmos_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-documents-azure-com" + properties = { + privateDnsZoneId = azapi_resource.cosmos_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource cosmosDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.documents.azure.com' + location: 'global' + } + + resource cosmosDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: cosmosDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource cosmosPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: cosmosPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-documents-azure-com' + properties: { + privateDnsZoneId: cosmosDnsZone.id + } + } + ] + } + } + template_check: + scope: + - cosmos-db + require_config: + - entra_rbac + - local_auth_disabled + error_message: 'Service ''{service_name}'' ({service_type}) missing {config_key}: true' + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + disableLocalAuth = true + publicNetworkAccess = "Disabled" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = false + } + ] + capabilities = [ + { + name = "EnableServerless" + } + ] + } + } + } + bicep_pattern: | + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + disableLocalAuth: true + publicNetworkAccess: 'Disabled' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: false + } + ] + capabilities: [ + { + name: 'EnableServerless' + } + ] + } + } + prohibitions: + - NEVER set disableLocalAuth to false — all access must use Entra RBAC + - NEVER use account-level keys (listKeys) for application access + - NEVER use Strong consistency for POC workloads — use Session or Eventual + - NEVER set publicNetworkAccess to Enabled +- id: AZ-CDB-002 + severity: recommended + description: Do not use Strong consistency for POC workloads + rationale: Strong consistency has significant latency and cost implications; Session is sufficient for most POCs + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + template_check: + scope: + - cosmos-db + reject_config_value: + consistency: strong + error_message: Service '{service_name}' ({service_type}) uses 'strong' consistency — consider Session or Eventual unless + Strong is justified + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +- id: AZ-CDB-003 + severity: recommended + description: Use autoscale throughput for variable workloads or serverless for POC + rationale: Avoids over-provisioning while handling traffic spikes; serverless has no idle cost + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - cost-analyst + template_check: + scope: + - cosmos-db + require_config: + - autoscale + severity: warning + error_message: Service '{service_name}' ({service_type}) missing autoscale configuration — consider autoscale throughput + for variable workloads + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # For provisioned autoscale (non-serverless): + resource "azapi_resource" "cosmos_sql_database" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 1000 + } + } + } + } + } + bicep_pattern: | + // For provisioned autoscale (non-serverless): + resource cosmosSqlDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 1000 + } + } + } + } +- id: AZ-CDB-004 + severity: recommended + description: Design partition keys based on query patterns, not just cardinality + rationale: Poor partition keys cause hot partitions and throttling + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + template_check: + scope: + - cosmos-db + require_config: + - partition_key + error_message: Service '{service_name}' ({service_type}) missing partition_key definition + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +- id: AZ-CDB-005 + severity: recommended + description: Enable continuous backup for point-in-time restore + rationale: 'WAF Reliability: Continuous backup provides point-in-time restore capability, recovering from accidental destructive + operations and restoring deleted resources' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # CRITICAL: backupPolicy MUST be set explicitly on the Cosmos DB account. + # Serverless accounts MUST use Continuous — ARM rejects Periodic for serverless. + # Omitting backupPolicy entirely causes undefined behavior on some API versions. + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" + } + } + bicep_pattern: | + // CRITICAL: backupPolicy MUST be set explicitly on the Cosmos DB account. + // Serverless accounts MUST use Continuous — ARM rejects Periodic for serverless. + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + prohibitions: + - NEVER omit backupPolicy on Cosmos DB accounts — explicit declaration is required + - NEVER use Periodic backup for serverless accounts — ARM rejects the deployment + - NEVER use Periodic backup for production workloads when Continuous is available +- id: AZ-CDB-006 + severity: recommended + description: Configure availability zone support on the Cosmos DB account + rationale: 'WAF Reliability: Availability zones provide segregated power, networking, and cooling, isolating hardware failures + to a subset of replicas' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # In the locations block of CDB-001, set isZoneRedundant = true: + # locations = [ + # { + # locationName = var.location + # failoverPriority = 0 + # isZoneRedundant = true + # } + # ] + bicep_pattern: | + // In the locations block of CDB-001, set isZoneRedundant to true: + // locations: [ + // { + // locationName: location + // failoverPriority: 0 + // isZoneRedundant: true + // } + // ] +- id: AZ-CDB-007 + severity: recommended + description: Enable Microsoft Defender for Cosmos DB + rationale: 'WAF Security: Detects attempts to exploit databases, including potential SQL injections, suspicious access patterns, + and other exploitation activities' + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +- id: AZ-CDB-008 + severity: recommended + description: Configure multi-region replication for critical workloads + rationale: 'WAF Reliability: Spanning multiple regions ensures workload resilience to regional outages with automatic failover; + enable service-managed failover for single-region write accounts' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +- id: AZ-CDB-009 + severity: recommended + description: Implement TTL (time-to-live) on containers with transient data + rationale: 'WAF Cost: TTL automatically deletes unnecessary data, keeping the database clutter-free and optimizing storage + costs' + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +- id: AZ-CDB-010 + severity: required + description: Enable diagnostic settings to Log Analytics workspace + rationale: Audit trail for data access and performance monitoring + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-cosmos + description: Diagnostic settings for Cosmos DB to Log Analytics + terraform_pattern: | + resource "azapi_resource" "cosmos_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.cosmos_account_name}" + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource cosmosDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: cosmosAccount + name: 'diag-${cosmosAccountName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts +patterns: +- name: Cosmos DB with Entra RBAC and private endpoint + description: Complete Cosmos DB deployment with local auth disabled, RBAC role assignment, private endpoint, and diagnostics +anti_patterns: +- description: Do not use account-level keys for application access + instead: Use Microsoft Entra RBAC with managed identity and Cosmos DB Built-in Data Contributor role +- description: Do not use unlimited containers without TTL policy + instead: Set TTL on containers with transient data +- description: Do not use Strong consistency unless explicitly justified + instead: Use Session consistency for most workloads +references: +- title: Cosmos DB security baseline + url: https://learn.microsoft.com/azure/cosmos-db/security-baseline +- title: Cosmos DB RBAC + url: https://learn.microsoft.com/azure/cosmos-db/how-to-setup-rbac +- title: Cosmos DB private endpoints + url: https://learn.microsoft.com/azure/cosmos-db/how-to-configure-private-endpoints +- title: 'WAF: Cosmos DB service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/cosmos-db +- title: Cosmos DB continuous backup + url: https://learn.microsoft.com/azure/cosmos-db/continuous-backup-restore-introduction +- title: Cosmos DB availability zones + url: https://learn.microsoft.com/azure/reliability/reliability-cosmos-db-nosql diff --git a/azext_prototype/governance/policies/azure/data/data-factory.policy.yaml b/azext_prototype/governance/policies/azure/data/data-factory.policy.yaml new file mode 100644 index 0000000..1039bb8 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/data-factory.policy.yaml @@ -0,0 +1,277 @@ +kind: policy +domain: azure-data +description: Governance policies for Data Factory +last_updated: '2026-03-27' +rules: +- id: AZ-ADF-001 + severity: required + description: Deploy Data Factory with managed identity, managed VNet integration, and public access disabled + rationale: Managed VNet isolates integration runtime traffic; managed identity eliminates stored credentials + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-adf + description: Private endpoint for Data Factory data plane with groupId 'dataFactory' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.datafactory.azure.net + description: Private DNS zone for Data Factory data plane endpoint resolution + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.adf.azure.com + description: Private DNS zone for Data Factory portal (authoring) endpoint resolution + - type: Microsoft.DataFactory/factories/managedVirtualNetworks@2018-06-01 + name: default + description: Managed virtual network isolating integration runtime data movement traffic + - type: Microsoft.DataFactory/factories/integrationRuntimes@2018-06-01 + name: AutoResolveIntegrationRuntime + description: Managed VNet integration runtime for secure data movement + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-adf + description: Diagnostic settings routing pipeline and activity logs to Log Analytics + targets: + - services: + - Microsoft.DataFactory/factories + terraform_pattern: | + resource "azapi_resource" "data_factory" { + type = "Microsoft.DataFactory/factories@2018-06-01" + name = var.adf_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + publicNetworkAccess = "Disabled" + purviewConfiguration = {} + globalParameters = {} + } + } + } + bicep_pattern: | + resource dataFactory 'Microsoft.DataFactory/factories@2018-06-01' = { + name: adfName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + publicNetworkAccess: 'Disabled' + purviewConfiguration: {} + globalParameters: {} + } + } + prohibitions: + - Do not enable publicNetworkAccess — use private endpoints + - Do not store credentials in linked services — use managed identity or Key Vault references + - Do not use self-hosted IR when managed VNet IR is sufficient +- id: AZ-ADF-002 + severity: required + description: Configure managed virtual network for integration runtime + rationale: Managed VNet ensures all data movement traffic stays within Azure backbone and supports managed private endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.DataFactory/factories/managedVirtualNetworks/managedPrivateEndpoints@2018-06-01 + name: mpe-datasource + description: Managed private endpoint connecting ADF integration runtime to data sources + targets: + - services: + - Microsoft.DataFactory/factories + terraform_pattern: | + resource "azapi_resource" "adf_managed_vnet" { + type = "Microsoft.DataFactory/factories/managedVirtualNetworks@2018-06-01" + name = "default" + parent_id = azapi_resource.data_factory.id + body = { + properties = {} + } + } + + resource "azapi_resource" "adf_managed_ir" { + type = "Microsoft.DataFactory/factories/integrationRuntimes@2018-06-01" + name = "AutoResolveIntegrationRuntime" + parent_id = azapi_resource.data_factory.id + body = { + properties = { + type = "Managed" + managedVirtualNetwork = { + referenceName = "default" + type = "ManagedVirtualNetworkReference" + } + typeProperties = { + computeProperties = { + location = "AutoResolve" + } + } + } + } + } + bicep_pattern: | + resource adfManagedVnet 'Microsoft.DataFactory/factories/managedVirtualNetworks@2018-06-01' = { + parent: dataFactory + name: 'default' + properties: {} + } + + resource adfManagedIr 'Microsoft.DataFactory/factories/integrationRuntimes@2018-06-01' = { + parent: dataFactory + name: 'AutoResolveIntegrationRuntime' + properties: { + type: 'Managed' + managedVirtualNetwork: { + referenceName: 'default' + type: 'ManagedVirtualNetworkReference' + } + typeProperties: { + computeProperties: { + location: 'AutoResolve' + } + } + } + } + prohibitions: + - Do not use the default Azure IR without managed VNet — data traffic flows over public internet +- id: AZ-ADF-003 + severity: required + description: Use Key Vault linked service for all secrets and connection strings + rationale: Storing credentials in ADF linked services is insecure; Key Vault centralizes secret management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-secrets + description: Key Vault storing secrets and connection strings referenced by ADF linked services + targets: + - services: + - Microsoft.DataFactory/factories + terraform_pattern: | + # Configure Key Vault linked service in ADF (typically done via ADF JSON definition) + # Grant ADF managed identity Key Vault Secrets User role + resource "azapi_resource" "adf_kv_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.role_assignment_name + parent_id = var.key_vault_id + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" + principalId = azapi_resource.data_factory.identity[0].principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + // Grant ADF managed identity Key Vault Secrets User role + resource adfKvRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVault.id, dataFactory.id, '4633458b-17de-408a-b874-0445c86b69e6') + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') + principalId: dataFactory.identity.principalId + principalType: 'ServicePrincipal' + } + } + prohibitions: + - Do not store passwords or connection strings directly in linked service definitions + - Do not grant Key Vault Administrator to ADF — use least-privilege Secrets User role +- id: AZ-ADF-004 + severity: recommended + description: Enable diagnostic settings for pipeline runs and activity logs + rationale: Monitor pipeline execution, trigger events, and integration runtime status for operational insight + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Data Factory diagnostic logs + targets: + - services: + - Microsoft.DataFactory/factories + terraform_pattern: | + resource "azapi_resource" "adf_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-data-factory" + parent_id = azapi_resource.data_factory.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "PipelineRuns" + enabled = true + }, + { + category = "ActivityRuns" + enabled = true + }, + { + category = "TriggerRuns" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource adfDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-data-factory' + scope: dataFactory + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'PipelineRuns' + enabled: true + } + { + category: 'ActivityRuns' + enabled: true + } + { + category: 'TriggerRuns' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit PipelineRuns and ActivityRuns logs — they are essential for debugging ETL failures +patterns: +- name: Data Factory with managed VNet and Key Vault integration + description: Production ADF with managed IR, private endpoints, and Key Vault for secrets + example: | + # See ADF-001 through ADF-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not store credentials in Data Factory linked service definitions + instead: Use Key Vault linked service with managed identity for all secrets +- description: Do not use the public Azure IR for production data movement + instead: Configure managed virtual network integration runtime +references: +- title: Data Factory documentation + url: https://learn.microsoft.com/azure/data-factory/introduction +- title: Data Factory managed virtual network + url: https://learn.microsoft.com/azure/data-factory/managed-virtual-network-private-endpoint diff --git a/azext_prototype/governance/policies/azure/data/databricks.policy.yaml b/azext_prototype/governance/policies/azure/data/databricks.policy.yaml new file mode 100644 index 0000000..5d438d5 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/databricks.policy.yaml @@ -0,0 +1,409 @@ +kind: policy +domain: azure-data +description: Governance policies for Databricks +last_updated: '2026-03-27' +rules: +- id: AZ-DBR-001 + severity: required + description: Deploy Databricks workspace with Premium SKU, VNet injection, and public access disabled + rationale: Premium SKU provides RBAC, audit logging, and CMK; VNet injection isolates cluster traffic + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-dbr-public, snet-dbr-private + description: Two delegated subnets for Databricks cluster nodes (public and private) + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-dbr + description: NSG with Databricks-required inbound/outbound rules on both subnets + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-dbr-ui-api, pe-dbr-browser + description: Private endpoints for Databricks workspace UI/API and browser authentication + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azuredatabricks.net + description: Private DNS zone for Databricks workspace private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-databricks + description: Diagnostic settings routing workspace and cluster logs to Log Analytics + targets: + - services: + - Microsoft.Databricks/workspaces + terraform_pattern: | + resource "azapi_resource" "databricks_workspace" { + type = "Microsoft.Databricks/workspaces@2024-05-01" + name = var.dbr_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "premium" + } + properties = { + managedResourceGroupId = "/subscriptions/${var.subscription_id}/resourceGroups/${var.managed_rg_name}" + publicNetworkAccess = "Disabled" + requiredNsgRules = "AllRules" + parameters = { + customVirtualNetworkId = { + value = var.vnet_id + } + customPublicSubnetName = { + value = var.public_subnet_name + } + customPrivateSubnetName = { + value = var.private_subnet_name + } + enableNoPublicIp = { + value = true + } + prepareEncryption = { + value = true + } + } + } + } + } + bicep_pattern: | + resource databricksWorkspace 'Microsoft.Databricks/workspaces@2024-05-01' = { + name: dbrName + location: location + sku: { + name: 'premium' + } + properties: { + managedResourceGroupId: '/subscriptions/${subscriptionId}/resourceGroups/${managedRgName}' + publicNetworkAccess: 'Disabled' + requiredNsgRules: 'AllRules' + parameters: { + customVirtualNetworkId: { + value: vnetId + } + customPublicSubnetName: { + value: publicSubnetName + } + customPrivateSubnetName: { + value: privateSubnetName + } + enableNoPublicIp: { + value: true + } + prepareEncryption: { + value: true + } + } + } + } + prohibitions: + - Do not use Standard SKU — it lacks RBAC, audit logging, and CMK support + - Do not enable publicNetworkAccess — use private endpoints for workspace access + - Do not set enableNoPublicIp to false — cluster nodes should not have public IPs + - Do not deploy Databricks without VNet injection +- id: AZ-DBR-002 + severity: required + description: Create two dedicated subnets delegated to Databricks with required NSG rules + rationale: Databricks requires separate public and private subnets with specific NSG rules for cluster communication + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-dbr + description: NSG with required Databricks communication rules for delegated subnets + targets: + - services: + - Microsoft.Databricks/workspaces + terraform_pattern: | + resource "azapi_resource" "dbr_public_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = var.dbr_public_subnet_name + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.dbr_public_prefix + networkSecurityGroup = { + id = azapi_resource.dbr_nsg.id + } + delegations = [ + { + name = "databricks-public" + properties = { + serviceName = "Microsoft.Databricks/workspaces" + } + } + ] + } + } + } + + resource "azapi_resource" "dbr_private_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = var.dbr_private_subnet_name + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.dbr_private_prefix + networkSecurityGroup = { + id = azapi_resource.dbr_nsg.id + } + delegations = [ + { + name = "databricks-private" + properties = { + serviceName = "Microsoft.Databricks/workspaces" + } + } + ] + } + } + } + bicep_pattern: | + resource dbrPublicSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: dbrPublicSubnetName + properties: { + addressPrefix: dbrPublicPrefix + networkSecurityGroup: { + id: dbrNsg.id + } + delegations: [ + { + name: 'databricks-public' + properties: { + serviceName: 'Microsoft.Databricks/workspaces' + } + } + ] + } + } + + resource dbrPrivateSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: dbrPrivateSubnetName + properties: { + addressPrefix: dbrPrivatePrefix + networkSecurityGroup: { + id: dbrNsg.id + } + delegations: [ + { + name: 'databricks-private' + properties: { + serviceName: 'Microsoft.Databricks/workspaces' + } + } + ] + } + } + prohibitions: + - Do not share Databricks subnets with other resources + - Do not use subnets smaller than /26 — Databricks needs IP space for cluster nodes +- id: AZ-DBR-003 + severity: recommended + description: Create private endpoints for workspace UI/API and browser authentication + rationale: Private endpoints ensure all workspace access stays on the private network + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azuredatabricks.net + description: Private DNS zone for Databricks private endpoint name resolution + - type: Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-04-01 + name: default + description: DNS zone group registering Databricks private endpoint records + targets: + - services: + - Microsoft.Databricks/workspaces + terraform_pattern: | + resource "azapi_resource" "dbr_pe_ui_api" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.dbr_name}-pe-ui-api" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.dbr_name}-ui-api" + properties = { + privateLinkServiceId = azapi_resource.databricks_workspace.id + groupIds = ["databricks_ui_api"] + } + } + ] + } + } + } + + resource "azapi_resource" "dbr_pe_browser" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.dbr_name}-pe-browser" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.dbr_name}-browser" + properties = { + privateLinkServiceId = azapi_resource.databricks_workspace.id + groupIds = ["browser_authentication"] + } + } + ] + } + } + } + bicep_pattern: | + resource dbrPeUiApi 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${dbrName}-pe-ui-api' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${dbrName}-ui-api' + properties: { + privateLinkServiceId: databricksWorkspace.id + groupIds: ['databricks_ui_api'] + } + } + ] + } + } + + resource dbrPeBrowser 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${dbrName}-pe-browser' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${dbrName}-browser' + properties: { + privateLinkServiceId: databricksWorkspace.id + groupIds: ['browser_authentication'] + } + } + ] + } + } + prohibitions: + - Do not skip the browser_authentication private endpoint — web UI access requires it +- id: AZ-DBR-004 + severity: recommended + description: Enable diagnostic settings for Databricks workspace + rationale: Track workspace access, job runs, cluster events, and notebook executions + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Databricks diagnostic logs + targets: + - services: + - Microsoft.Databricks/workspaces + terraform_pattern: | + resource "azapi_resource" "dbr_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-databricks" + parent_id = azapi_resource.databricks_workspace.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "dbfs" + enabled = true + }, + { + category = "clusters" + enabled = true + }, + { + category = "accounts" + enabled = true + }, + { + category = "jobs" + enabled = true + }, + { + category = "notebook" + enabled = true + }, + { + category = "workspace" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource dbrDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-databricks' + scope: databricksWorkspace + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'dbfs' + enabled: true + } + { + category: 'clusters' + enabled: true + } + { + category: 'accounts' + enabled: true + } + { + category: 'jobs' + enabled: true + } + { + category: 'notebook' + enabled: true + } + { + category: 'workspace' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit accounts logs — they track authentication and authorization events +patterns: +- name: Databricks Premium with VNet injection and private endpoints + description: Fully isolated Databricks workspace with no public IPs and workspace-level encryption + example: | + # See DBR-001 through DBR-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy Databricks without VNet injection + instead: Use customVirtualNetworkId parameter with dedicated subnets +- description: Do not use Standard SKU for production + instead: Use Premium SKU for RBAC, audit logging, and CMK support +references: +- title: Databricks VNet injection + url: https://learn.microsoft.com/azure/databricks/administration-guide/cloud-configurations/azure/vnet-inject +- title: Databricks security best practices + url: https://learn.microsoft.com/azure/databricks/security/best-practices diff --git a/azext_prototype/governance/policies/azure/data/event-grid.policy.yaml b/azext_prototype/governance/policies/azure/data/event-grid.policy.yaml new file mode 100644 index 0000000..1ae9bf7 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/event-grid.policy.yaml @@ -0,0 +1,324 @@ +kind: policy +domain: azure-data +description: Governance policies for Event Grid +last_updated: '2026-03-27' +rules: +- id: AZ-EG-001 + severity: required + description: Deploy Event Grid topic with managed identity, TLS 1.2, local auth disabled, and public access off + rationale: Managed identity enables secure delivery; disabling local auth prevents SAS key usage + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-eventgrid + description: Private endpoint for Event Grid topic with groupId 'topic' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.eventgrid.azure.net + description: Private DNS zone for Event Grid private endpoint resolution + - type: Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview + name: eg-subscription + description: Event subscription defining delivery destination and filtering rules + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-eventgrid + description: Diagnostic settings routing delivery and publish failure logs to Log Analytics + targets: + - services: + - Microsoft.EventGrid/topics + terraform_pattern: | + resource "azapi_resource" "event_grid_topic" { + type = "Microsoft.EventGrid/topics@2024-06-01-preview" + name = var.eg_topic_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + inputSchema = "EventGridSchema" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + minimumTlsVersionAllowed = "1.2" + dataResidencyBoundary = "WithinGeopair" + } + } + } + bicep_pattern: | + resource eventGridTopic 'Microsoft.EventGrid/topics@2024-06-01-preview' = { + name: egTopicName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + inputSchema: 'EventGridSchema' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + minimumTlsVersionAllowed: '1.2' + dataResidencyBoundary: 'WithinGeopair' + } + } + prohibitions: + - Do not enable publicNetworkAccess — use private endpoints + - Do not enable local auth (SAS keys) — use Entra RBAC + - Do not allow TLS versions below 1.2 +- id: AZ-EG-002 + severity: required + description: Configure event subscriptions with dead-letter destination and retry policy + rationale: Without dead-letter, undeliverable events are lost; retry policy handles transient failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Storage/storageAccounts@2023-01-01 + name: st-deadletter + description: Storage account hosting the dead-letter blob container for undeliverable events + targets: + - services: + - Microsoft.EventGrid/topics + terraform_pattern: | + resource "azapi_resource" "eg_subscription" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = var.subscription_name + parent_id = azapi_resource.event_grid_topic.id + body = { + properties = { + destination = { + endpointType = "WebHook" + properties = { + endpointUrl = var.webhook_url + maxEventsPerBatch = 1 + preferredBatchSizeInKilobytes = 64 + } + } + retryPolicy = { + maxDeliveryAttempts = 30 + eventTimeToLiveInMinutes = 1440 + } + deadLetterDestination = { + endpointType = "StorageBlob" + properties = { + resourceId = var.storage_account_id + blobContainerName = "dead-letters" + } + } + filter = { + isSubjectCaseSensitive = false + } + } + } + } + bicep_pattern: | + resource egSubscription 'Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview' = { + parent: eventGridTopic + name: subscriptionName + properties: { + destination: { + endpointType: 'WebHook' + properties: { + endpointUrl: webhookUrl + maxEventsPerBatch: 1 + preferredBatchSizeInKilobytes: 64 + } + } + retryPolicy: { + maxDeliveryAttempts: 30 + eventTimeToLiveInMinutes: 1440 + } + deadLetterDestination: { + endpointType: 'StorageBlob' + properties: { + resourceId: storageAccountId + blobContainerName: 'dead-letters' + } + } + filter: { + isSubjectCaseSensitive: false + } + } + } + prohibitions: + - Do not create event subscriptions without a dead-letter destination + - Do not set maxDeliveryAttempts to 1 — transient failures will immediately discard events + - Do not hardcode webhook URLs with embedded credentials +- id: AZ-EG-003 + severity: recommended + description: Use managed identity for event delivery to Azure destinations + rationale: Managed identity eliminates the need for access keys or connection strings in delivery configuration + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Event Grid Data Sender + description: Grants Event Grid identity permission to send events to the destination resource + targets: + - services: + - Microsoft.EventGrid/topics + terraform_pattern: | + # For Azure destinations (Event Hubs, Service Bus, Storage Queue), use deliveryWithResourceIdentity + resource "azapi_resource" "eg_subscription_msi" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = var.subscription_name + parent_id = azapi_resource.event_grid_topic.id + body = { + properties = { + deliveryWithResourceIdentity = { + identity = { + type = "SystemAssigned" + } + destination = { + endpointType = "EventHub" + properties = { + resourceId = var.eventhub_id + } + } + } + retryPolicy = { + maxDeliveryAttempts = 30 + eventTimeToLiveInMinutes = 1440 + } + deadLetterWithResourceIdentity = { + identity = { + type = "SystemAssigned" + } + deadLetterDestination = { + endpointType = "StorageBlob" + properties = { + resourceId = var.storage_account_id + blobContainerName = "dead-letters" + } + } + } + } + } + } + bicep_pattern: | + // For Azure destinations, use deliveryWithResourceIdentity + resource egSubscriptionMsi 'Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview' = { + parent: eventGridTopic + name: subscriptionName + properties: { + deliveryWithResourceIdentity: { + identity: { + type: 'SystemAssigned' + } + destination: { + endpointType: 'EventHub' + properties: { + resourceId: eventhubId + } + } + } + retryPolicy: { + maxDeliveryAttempts: 30 + eventTimeToLiveInMinutes: 1440 + } + deadLetterWithResourceIdentity: { + identity: { + type: 'SystemAssigned' + } + deadLetterDestination: { + endpointType: 'StorageBlob' + properties: { + resourceId: storageAccountId + blobContainerName: 'dead-letters' + } + } + } + } + } + prohibitions: + - Do not use connection strings for Azure destination delivery — use managed identity +- id: AZ-EG-004 + severity: recommended + description: Enable diagnostic settings for Event Grid topic + rationale: Monitor delivery success rates, failures, and dead-lettered events + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Event Grid diagnostic logs + targets: + - services: + - Microsoft.EventGrid/topics + terraform_pattern: | + resource "azapi_resource" "eg_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-event-grid" + parent_id = azapi_resource.event_grid_topic.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "DeliveryFailures" + enabled = true + }, + { + category = "PublishFailures" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource egDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-event-grid' + scope: eventGridTopic + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'DeliveryFailures' + enabled: true + } + { + category: 'PublishFailures' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit DeliveryFailures logs — they are critical for diagnosing event loss +patterns: +- name: Event Grid topic with private endpoint and dead-letter + description: Production Event Grid with Entra auth, private endpoint, and dead-letter storage + example: | + # See EG-001 through EG-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use SAS keys for Event Grid authentication + instead: Disable local auth and use Entra RBAC with managed identity +- description: Do not create event subscriptions without dead-letter configuration + instead: Always configure a dead-letter destination for undeliverable events +references: +- title: Event Grid documentation + url: https://learn.microsoft.com/azure/event-grid/overview +- title: Event Grid security + url: https://learn.microsoft.com/azure/event-grid/security-authentication diff --git a/azext_prototype/governance/policies/azure/data/event-hubs.policy.yaml b/azext_prototype/governance/policies/azure/data/event-hubs.policy.yaml new file mode 100644 index 0000000..caf0c97 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/event-hubs.policy.yaml @@ -0,0 +1,352 @@ +kind: policy +domain: azure-data +description: Governance policies for Event Hubs +last_updated: '2026-03-27' +rules: +- id: AZ-EH-001 + severity: required + description: Deploy Event Hubs namespace with Standard or Premium SKU, TLS 1.2, and local auth disabled + rationale: Basic SKU lacks consumer groups and capture; local auth bypass Entra RBAC controls + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-eventhubs + description: Private endpoint for Event Hubs namespace with groupId 'namespace' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.servicebus.windows.net + description: Private DNS zone for Event Hubs private endpoint resolution + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Azure Event Hubs Data Sender/Receiver + description: RBAC roles granting send and receive permissions on the Event Hubs namespace + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-eventhubs + description: Diagnostic settings routing operational and audit logs to Log Analytics + targets: + - services: + - Microsoft.EventHub/namespaces + terraform_pattern: | + resource "azapi_resource" "eventhub_namespace" { + type = "Microsoft.EventHub/namespaces@2024-01-01" + name = var.eh_namespace_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = "Standard" + tier = "Standard" + capacity = var.throughput_units + } + properties = { + isAutoInflateEnabled = true + maximumThroughputUnits = var.max_throughput_units + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + zoneRedundant = true + kafkaEnabled = true + } + } + } + bicep_pattern: | + resource eventhubNamespace 'Microsoft.EventHub/namespaces@2024-01-01' = { + name: ehNamespaceName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + tier: 'Standard' + capacity: throughputUnits + } + properties: { + isAutoInflateEnabled: true + maximumThroughputUnits: maxThroughputUnits + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + zoneRedundant: true + kafkaEnabled: true + } + } + prohibitions: + - Do not use Basic SKU — it lacks consumer groups, capture, and partitioned consumers + - Do not enable publicNetworkAccess — use private endpoints + - Do not enable local auth (SAS keys) — use Entra RBAC + - Do not allow TLS versions below 1.2 +- id: AZ-EH-002 + severity: required + description: Create Event Hubs with appropriate partition count and message retention + rationale: Partition count determines parallelism and cannot be changed after creation; retention affects data availability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01 + name: cg-app + description: Dedicated consumer group for each consuming application + targets: + - services: + - Microsoft.EventHub/namespaces + terraform_pattern: | + resource "azapi_resource" "eventhub" { + type = "Microsoft.EventHub/namespaces/eventhubs@2024-01-01" + name = var.eventhub_name + parent_id = azapi_resource.eventhub_namespace.id + body = { + properties = { + partitionCount = var.partition_count + messageRetentionInDays = 7 + status = "Active" + } + } + } + bicep_pattern: | + resource eventhub 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = { + parent: eventhubNamespace + name: eventhubName + properties: { + partitionCount: partitionCount + messageRetentionInDays: 7 + status: 'Active' + } + } + prohibitions: + - Do not set partitionCount to 1 for production — it eliminates parallelism + - Do not use the $Default consumer group for production applications +- id: AZ-EH-003 + severity: required + description: Create dedicated consumer groups for each consuming application + rationale: Shared consumer groups cause checkpoint conflicts and message loss between applications + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: [] + targets: + - services: + - Microsoft.EventHub/namespaces + terraform_pattern: | + resource "azapi_resource" "consumer_group" { + type = "Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01" + name = var.consumer_group_name + parent_id = azapi_resource.eventhub.id + body = { + properties = { + userMetadata = var.consumer_description + } + } + } + bicep_pattern: | + resource consumerGroup 'Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01' = { + parent: eventhub + name: consumerGroupName + properties: { + userMetadata: consumerDescription + } + } + prohibitions: + - Do not use the $Default consumer group for production workloads + - Do not share consumer groups between different applications +- id: AZ-EH-004 + severity: recommended + description: Enable Event Hubs Capture for cold-path analytics + rationale: 'WAF Reliability/Operational Excellence: Capture automatically delivers streaming data to Azure Blob Storage + or Data Lake, providing a durable copy of events for replay and analytics' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.EventHub/namespaces + terraform_pattern: | + resource "azapi_resource" "eventhub_with_capture" { + type = "Microsoft.EventHub/namespaces/eventhubs@2024-01-01" + name = var.eventhub_name + parent_id = azapi_resource.eventhub_namespace.id + body = { + properties = { + partitionCount = var.partition_count + messageRetentionInDays = 7 + captureDescription = { + enabled = true + encoding = "Avro" + intervalInSeconds = 300 + sizeLimitInBytes = 314572800 + destination = { + name = "EventHubArchive.AzureBlockBlob" + properties = { + storageAccountResourceId = var.capture_storage_account_id + blobContainer = var.capture_container_name + archiveNameFormat = "{Namespace}/{EventHub}/{PartitionId}/{Year}/{Month}/{Day}/{Hour}/{Minute}/{Second}" + } + } + } + } + } + } + bicep_pattern: | + resource eventhubWithCapture 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = { + parent: eventhubNamespace + name: eventhubName + properties: { + partitionCount: partitionCount + messageRetentionInDays: 7 + captureDescription: { + enabled: true + encoding: 'Avro' + intervalInSeconds: 300 + sizeLimitInBytes: 314572800 + destination: { + name: 'EventHubArchive.AzureBlockBlob' + properties: { + storageAccountResourceId: captureStorageAccountId + blobContainer: captureContainerName + archiveNameFormat: '{Namespace}/{EventHub}/{PartitionId}/{Year}/{Month}/{Day}/{Hour}/{Minute}/{Second}' + } + } + } + } + } +- id: AZ-EH-005 + severity: recommended + description: Enable geo-disaster recovery pairing for critical namespaces + rationale: 'WAF Reliability: Geo-DR creates a metadata-only pairing to a secondary namespace in another region, enabling + failover of namespace metadata during regional outages' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.EventHub/namespaces +- id: AZ-EH-006 + severity: recommended + description: Use schema registry for event schema management and evolution + rationale: 'WAF Operational Excellence: Schema registry provides a centralized repository for event schemas, enabling schema + validation and versioned evolution across producers and consumers' + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.EventHub/namespaces +- id: AZ-EH-007 + severity: recommended + description: Enable diagnostic settings for Event Hubs namespace + rationale: Monitor throughput, errors, and throttled requests for capacity planning + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Event Hubs diagnostic logs + targets: + - services: + - Microsoft.EventHub/namespaces + terraform_pattern: | + resource "azapi_resource" "eh_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-eventhubs" + parent_id = azapi_resource.eventhub_namespace.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "ArchiveLogs" + enabled = true + }, + { + category = "OperationalLogs" + enabled = true + }, + { + category = "AutoScaleLogs" + enabled = true + }, + { + category = "RuntimeAuditLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource ehDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-eventhubs' + scope: eventhubNamespace + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'ArchiveLogs' + enabled: true + } + { + category: 'OperationalLogs' + enabled: true + } + { + category: 'AutoScaleLogs' + enabled: true + } + { + category: 'RuntimeAuditLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit RuntimeAuditLogs — they track authentication and authorization events +patterns: +- name: Event Hubs namespace with Entra RBAC and private endpoint + description: Standard namespace with local auth disabled, private endpoint, and diagnostics + example: | + # See EH-001 through EH-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use SAS keys for Event Hub authentication + instead: Disable local auth and use Entra RBAC with managed identity +- description: Do not share consumer groups between applications + instead: Create a dedicated consumer group per consuming application +references: +- title: Event Hubs documentation + url: https://learn.microsoft.com/azure/event-hubs/event-hubs-about +- title: Event Hubs security + url: https://learn.microsoft.com/azure/event-hubs/event-hubs-security-controls +- title: 'WAF: Event Hubs service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/event-hubs +- title: Event Hubs Capture + url: https://learn.microsoft.com/azure/event-hubs/event-hubs-capture-overview +- title: Event Hubs geo-disaster recovery + url: https://learn.microsoft.com/azure/event-hubs/event-hubs-geo-dr diff --git a/azext_prototype/governance/policies/azure/data/fabric.policy.yaml b/azext_prototype/governance/policies/azure/data/fabric.policy.yaml new file mode 100644 index 0000000..3db1a75 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/fabric.policy.yaml @@ -0,0 +1,118 @@ +kind: policy +domain: azure-data +description: Governance policies for Fabric +last_updated: '2026-03-27' +rules: +- id: AZ-FAB-001 + severity: required + description: Deploy Microsoft Fabric capacity with managed identity and appropriate SKU sizing + rationale: Fabric capacity is the compute foundation; proper sizing prevents over-provisioning and cost overruns + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-fabric + description: Diagnostic settings for Fabric capacity operation logs + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Fabric Capacity Contributor + description: RBAC role assignment for Fabric capacity management — separate from workspace permissions + targets: + - services: + - Microsoft.Fabric/capacities + terraform_pattern: | + resource "azapi_resource" "fabric_capacity" { + type = "Microsoft.Fabric/capacities@2023-11-01" + name = var.fabric_capacity_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = var.sku_name # "F2", "F4", "F8", "F16", "F32", "F64", "F128", "F256", "F512", "F1024", "F2048" + tier = "Fabric" + } + properties = { + administration = { + members = var.capacity_admin_upns + } + } + } + } + bicep_pattern: | + resource fabricCapacity 'Microsoft.Fabric/capacities@2023-11-01' = { + name: fabricCapacityName + location: location + sku: { + name: skuName + tier: 'Fabric' + } + properties: { + administration: { + members: capacityAdminUpns + } + } + } + prohibitions: + - Never over-provision Fabric capacity SKU — start with smallest SKU and scale up based on CU consumption + - Never grant capacity admin to broad groups — limit to dedicated administrators + - Never skip Fabric tenant settings configuration — data exfiltration and sharing controls are tenant-level + - Never hardcode admin UPNs — use variables for environment-specific configuration +- id: AZ-FAB-002 + severity: required + description: Configure Fabric tenant settings for data exfiltration prevention and guest access control + rationale: Tenant settings control data sharing, export, and external collaboration — misconfiguration leads to data leakage + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Fabric/capacities +- id: AZ-FAB-003 + severity: required + description: Enable Fabric audit logging and route to Log Analytics + rationale: Audit logs track data access, sharing, and workspace changes for compliance and security monitoring + applies_to: + - cloud-architect + - security-reviewer + - monitoring-agent + targets: + - services: + - Microsoft.Fabric/capacities +- id: AZ-FAB-004 + severity: recommended + description: Configure auto-pause and auto-resume for cost optimization + rationale: Fabric capacities incur cost even when idle; auto-pause reduces spend during off-hours + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Fabric/capacities +- id: AZ-FAB-005 + severity: recommended + description: Use managed private endpoints for secure data source connectivity + rationale: Managed private endpoints eliminate public exposure of on-premises and Azure data sources + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Fabric/capacities +patterns: +- name: Fabric capacity with admin governance + description: Fabric capacity with limited administrators, audit logging, and cost controls +anti_patterns: +- description: Do not over-provision Fabric capacity + instead: Start with smallest SKU (F2 for dev, F64+ for production) and scale based on CU utilization +- description: Do not leave tenant settings at defaults + instead: Explicitly configure data export restrictions, guest access, and sharing controls +references: +- title: Microsoft Fabric documentation + url: https://learn.microsoft.com/fabric/get-started/microsoft-fabric-overview +- title: Fabric administration and governance + url: https://learn.microsoft.com/fabric/admin/admin-overview diff --git a/azext_prototype/governance/policies/azure/data/iot-hub.policy.yaml b/azext_prototype/governance/policies/azure/data/iot-hub.policy.yaml new file mode 100644 index 0000000..e52153a --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/iot-hub.policy.yaml @@ -0,0 +1,273 @@ +kind: policy +domain: azure-data +description: Governance policies for Iot Hub +last_updated: '2026-03-27' +rules: +- id: AZ-IOT-001 + severity: required + description: Deploy IoT Hub with Standard tier, managed identity, TLS 1.2, and public access disabled + rationale: Standard tier supports cloud-to-device messaging and routing; managed identity eliminates connection strings + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-iothub + description: Private endpoint for IoT Hub with groupId 'iotHub' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azure-devices.net + description: Private DNS zone for IoT Hub private endpoint resolution + - type: Microsoft.Devices/provisioningServices@2022-12-12 + name: dps + description: Device Provisioning Service for automated X.509 device enrollment + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-iothub + description: Diagnostic settings routing connection, telemetry, and routing logs to Log Analytics + targets: + - services: + - Microsoft.Devices/IotHubs + terraform_pattern: | + resource "azapi_resource" "iot_hub" { + type = "Microsoft.Devices/IotHubs@2023-06-30" + name = var.iot_hub_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = "S1" + capacity = var.iot_hub_units + } + properties = { + minTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + features = "None" + routing = { + fallbackRoute = { + name = "fallback" + source = "DeviceMessages" + condition = "true" + endpointNames = ["events"] + isEnabled = true + } + } + networkRuleSets = { + defaultAction = "Deny" + applyToBuiltInEventHubEndpoint = true + ipRules = [] + } + } + } + } + bicep_pattern: | + resource iotHub 'Microsoft.Devices/IotHubs@2023-06-30' = { + name: iotHubName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'S1' + capacity: iotHubUnits + } + properties: { + minTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + features: 'None' + routing: { + fallbackRoute: { + name: 'fallback' + source: 'DeviceMessages' + condition: 'true' + endpointNames: ['events'] + isEnabled: true + } + } + networkRuleSets: { + defaultAction: 'Deny' + applyToBuiltInEventHubEndpoint: true + ipRules: [] + } + } + } + prohibitions: + - Do not use Basic tier — it lacks cloud-to-device messaging, device twins, and routing + - Do not use Free tier for production + - Do not enable publicNetworkAccess — use private endpoints + - Do not enable local auth — use Entra RBAC for service operations + - Do not allow TLS versions below 1.2 +- id: AZ-IOT-002 + severity: required + description: Use X.509 certificates or TPM attestation for device authentication + rationale: Symmetric keys are less secure and harder to rotate at scale; X.509 provides stronger device identity + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Devices/IotHubs@2023-06-30 + name: iot-hub + description: Parent IoT Hub that the DPS enrollment connects to + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-certs + description: Key Vault storing X.509 CA certificates for device authentication + targets: + - services: + - Microsoft.Devices/IotHubs + terraform_pattern: | + # Device authentication is configured at the device level, not in the IoT Hub resource + # Use Device Provisioning Service (DPS) with X.509 enrollment groups + resource "azapi_resource" "dps" { + type = "Microsoft.Devices/provisioningServices@2022-12-12" + name = var.dps_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "S1" + capacity = 1 + } + properties = { + publicNetworkAccess = "Disabled" + iotHubs = [ + { + connectionString = "" + location = var.location + name = "${var.iot_hub_name}.azure-devices.net" + } + ] + } + } + } + bicep_pattern: | + // Device authentication is configured at the device level, not in the IoT Hub resource + // Use Device Provisioning Service (DPS) with X.509 enrollment groups + resource dps 'Microsoft.Devices/provisioningServices@2022-12-12' = { + name: dpsName + location: location + sku: { + name: 'S1' + capacity: 1 + } + properties: { + publicNetworkAccess: 'Disabled' + iotHubs: [ + { + connectionString: '' + location: location + name: '${iotHubName}.azure-devices.net' + } + ] + } + } + prohibitions: + - Do not use symmetric keys for production device fleets — they cannot be rotated individually + - Do not embed device connection strings in application code +- id: AZ-IOT-003 + severity: recommended + description: Enable diagnostic settings for IoT Hub operations and device telemetry + rationale: Monitor device connections, message routing, and error rates for operational visibility + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for IoT Hub diagnostic logs + targets: + - services: + - Microsoft.Devices/IotHubs + terraform_pattern: | + resource "azapi_resource" "iot_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-iot-hub" + parent_id = azapi_resource.iot_hub.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "Connections" + enabled = true + }, + { + category = "DeviceTelemetry" + enabled = true + }, + { + category = "Routes" + enabled = true + }, + { + category = "C2DCommands" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource iotDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-iot-hub' + scope: iotHub + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'Connections' + enabled: true + } + { + category: 'DeviceTelemetry' + enabled: true + } + { + category: 'Routes' + enabled: true + } + { + category: 'C2DCommands' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit Connections logs — they are essential for device connectivity troubleshooting +patterns: +- name: IoT Hub Standard with private endpoint and DPS + description: Production IoT Hub with Entra auth, private endpoints, and device provisioning + example: | + # See IOT-001 through IOT-003 for complete azapi_resource patterns +anti_patterns: +- description: Do not expose IoT Hub to the public internet + instead: Disable public access and use private endpoints +- description: Do not use symmetric keys for large device fleets + instead: Use X.509 certificates with Device Provisioning Service +references: +- title: IoT Hub documentation + url: https://learn.microsoft.com/azure/iot-hub/iot-concepts-and-iot-hub +- title: IoT Hub security + url: https://learn.microsoft.com/azure/iot-hub/iot-hub-security-overview diff --git a/azext_prototype/governance/policies/azure/data/mysql-flexible.policy.yaml b/azext_prototype/governance/policies/azure/data/mysql-flexible.policy.yaml new file mode 100644 index 0000000..757eddc --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/mysql-flexible.policy.yaml @@ -0,0 +1,290 @@ +kind: policy +domain: azure-data +description: Governance policies for Mysql Flexible +last_updated: '2026-03-27' +rules: +- id: AZ-MYSQL-001 + severity: required + description: Deploy MySQL Flexible Server with Microsoft Entra authentication and TLS 1.2 enforcement + rationale: Entra auth eliminates password management; TLS 1.2 prevents protocol downgrade attacks + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-mysql + description: Delegated subnet with Microsoft.DBforMySQL/flexibleServers service delegation + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.mysql.database.azure.com + description: Private DNS zone for MySQL Flexible Server VNet-integrated name resolution + - type: Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01 + name: link-mysql-dns + description: VNet link connecting the MySQL private DNS zone to the virtual network + - type: Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30 + name: tls_version + description: Server configuration enforcing TLS 1.2 and audit log settings + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-mysql + description: Diagnostic settings routing MySQL audit and slow query logs to Log Analytics + targets: + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "mysql_flexible" { + type = "Microsoft.DBforMySQL/flexibleServers@2023-12-30" + name = var.mysql_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = var.sku_name + tier = "GeneralPurpose" + } + properties = { + version = "8.0.21" + administratorLogin = var.admin_login + administratorLoginPassword = var.admin_password + storage = { + storageSizeGB = var.storage_size_gb + autoGrow = "Enabled" + autoIoScaling = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" + } + highAvailability = { + mode = "ZoneRedundant" + } + network = { + delegatedSubnetResourceId = var.delegated_subnet_id + privateDnsZoneResourceId = var.private_dns_zone_id + publicNetworkAccess = "Disabled" + } + } + } + } + bicep_pattern: | + resource mysqlFlexible 'Microsoft.DBforMySQL/flexibleServers@2023-12-30' = { + name: mysqlName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + tier: 'GeneralPurpose' + } + properties: { + version: '8.0.21' + administratorLogin: adminLogin + administratorLoginPassword: adminPassword + storage: { + storageSizeGB: storageSizeGb + autoGrow: 'Enabled' + autoIoScaling: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + network: { + delegatedSubnetResourceId: delegatedSubnetId + privateDnsZoneResourceId: privateDnsZoneId + publicNetworkAccess: 'Disabled' + } + } + } + prohibitions: + - Do not enable publicNetworkAccess — use VNet integration or private endpoints + - Do not hardcode administratorLoginPassword in templates — use Key Vault references + - Do not use Burstable tier for production workloads with HA requirements +- id: AZ-MYSQL-002 + severity: required + description: Enforce TLS 1.2 via server configuration parameters + rationale: TLS version enforcement must be set at the server parameter level in addition to network config + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "mysql_tls_config" { + type = "Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30" + name = "tls_version" + parent_id = azapi_resource.mysql_flexible.id + body = { + properties = { + value = "TLSv1.2" + source = "user-override" + } + } + } + + resource "azapi_resource" "mysql_require_ssl" { + type = "Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30" + name = "require_secure_transport" + parent_id = azapi_resource.mysql_flexible.id + body = { + properties = { + value = "ON" + source = "user-override" + } + } + } + bicep_pattern: | + resource mysqlTlsConfig 'Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30' = { + parent: mysqlFlexible + name: 'tls_version' + properties: { + value: 'TLSv1.2' + source: 'user-override' + } + } + + resource mysqlRequireSsl 'Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30' = { + parent: mysqlFlexible + name: 'require_secure_transport' + properties: { + value: 'ON' + source: 'user-override' + } + } + prohibitions: + - Do not allow TLS 1.0 or 1.1 — they have known vulnerabilities + - Do not set require_secure_transport to OFF +- id: AZ-MYSQL-003 + severity: required + description: Enable audit logging for MySQL Flexible Server + rationale: Audit logs track connection attempts, DDL changes, and DML operations for compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for MySQL audit logs + targets: + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "mysql_audit_config" { + type = "Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30" + name = "audit_log_enabled" + parent_id = azapi_resource.mysql_flexible.id + body = { + properties = { + value = "ON" + source = "user-override" + } + } + } + + resource "azapi_resource" "mysql_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-mysql" + parent_id = azapi_resource.mysql_flexible.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "MySqlAuditLogs" + enabled = true + }, + { + category = "MySqlSlowLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource mysqlAuditConfig 'Microsoft.DBforMySQL/flexibleServers/configurations@2023-12-30' = { + parent: mysqlFlexible + name: 'audit_log_enabled' + properties: { + value: 'ON' + source: 'user-override' + } + } + + resource mysqlDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-mysql' + scope: mysqlFlexible + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'MySqlAuditLogs' + enabled: true + } + { + category: 'MySqlSlowLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not disable audit logging in production +- id: AZ-MYSQL-004 + severity: recommended + description: Enable zone-redundant high availability for production + rationale: Zone-redundant HA provides automatic failover across availability zones + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + # Set highAvailability.mode = "ZoneRedundant" in server properties + # See MYSQL-001 terraform_pattern for full example + bicep_pattern: | + // Set highAvailability.mode: 'ZoneRedundant' in server properties + // See MYSQL-001 bicep_pattern for full example + prohibitions: + - Do not use SameZone HA mode for production — it does not protect against zone failures +patterns: +- name: MySQL Flexible Server with VNet integration and HA + description: Production MySQL with zone-redundant HA, VNet integration, and audit logging + example: | + # See MYSQL-001 through MYSQL-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not expose MySQL to the public internet + instead: Use VNet integration with delegated subnet or private endpoints +- description: Do not store database passwords in plain text + instead: Use Key Vault references for administratorLoginPassword +references: +- title: MySQL Flexible Server documentation + url: https://learn.microsoft.com/azure/mysql/flexible-server/overview +- title: MySQL Flexible Server networking + url: https://learn.microsoft.com/azure/mysql/flexible-server/concepts-networking diff --git a/azext_prototype/governance/policies/azure/data/postgresql-flexible.policy.yaml b/azext_prototype/governance/policies/azure/data/postgresql-flexible.policy.yaml new file mode 100644 index 0000000..f9605da --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/postgresql-flexible.policy.yaml @@ -0,0 +1,263 @@ +kind: policy +domain: azure-data +description: Governance policies for Postgresql Flexible +last_updated: '2026-03-27' +rules: +- id: AZ-PG-001 + severity: required + description: Deploy PostgreSQL Flexible Server with Microsoft Entra authentication, VNet integration, and TLS 1.2 + rationale: Entra auth centralizes identity; VNet integration eliminates public exposure; TLS 1.2 prevents downgrade attacks + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-postgresql + description: Delegated subnet with Microsoft.DBforPostgreSQL/flexibleServers service delegation + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.postgres.database.azure.com + description: Private DNS zone for PostgreSQL Flexible Server VNet-integrated name resolution + - type: Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01 + name: link-pg-dns + description: VNet link connecting the PostgreSQL private DNS zone to the virtual network + - type: Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01 + name: entra-admin + description: Entra ID admin assignment enabling Azure AD authentication on the server + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-postgresql + description: Diagnostic settings routing PostgreSQL logs to Log Analytics + targets: + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "pg_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.pg_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = var.sku_name + tier = "GeneralPurpose" + } + properties = { + version = "16" + administratorLogin = var.admin_login + administratorLoginPassword = var.admin_password + authConfig = { + activeDirectoryAuth = "Enabled" + passwordAuth = "Disabled" + tenantId = var.tenant_id + } + storage = { + storageSizeGB = var.storage_size_gb + autoGrow = "Enabled" + tier = "P30" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" + } + highAvailability = { + mode = "ZoneRedundant" + } + network = { + delegatedSubnetResourceId = var.delegated_subnet_id + privateDnsZoneArmResourceId = var.private_dns_zone_id + publicNetworkAccess = "Disabled" + } + } + } + } + bicep_pattern: | + resource pgFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: pgName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + tier: 'GeneralPurpose' + } + properties: { + version: '16' + administratorLogin: adminLogin + administratorLoginPassword: adminPassword + authConfig: { + activeDirectoryAuth: 'Enabled' + passwordAuth: 'Disabled' + tenantId: tenantId + } + storage: { + storageSizeGB: storageSizeGb + autoGrow: 'Enabled' + tier: 'P30' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + network: { + delegatedSubnetResourceId: delegatedSubnetId + privateDnsZoneArmResourceId: privateDnsZoneId + publicNetworkAccess: 'Disabled' + } + } + } + prohibitions: + - Do not enable publicNetworkAccess — use VNet integration or private endpoints + - Do not hardcode administratorLoginPassword in templates — use Key Vault references + - Do not use passwordAuth Enabled when Entra auth is available + - Do not use Burstable tier for production workloads requiring HA +- id: AZ-PG-002 + severity: required + description: Configure Entra admin for PostgreSQL Flexible Server + rationale: Entra admin is required for Entra authentication to function + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01 + name: pg-server + description: Parent PostgreSQL server with activeDirectoryAuth enabled in authConfig + targets: + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "pg_entra_admin" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01" + name = var.entra_admin_object_id + parent_id = azapi_resource.pg_flexible.id + body = { + properties = { + principalName = var.entra_admin_name + principalType = "Group" + tenantId = var.tenant_id + } + } + } + bicep_pattern: | + resource pgEntraAdmin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2024-08-01' = { + parent: pgFlexible + name: entraAdminObjectId + properties: { + principalName: entraAdminName + principalType: 'Group' + tenantId: tenantId + } + } + prohibitions: + - Do not use individual user accounts as Entra admin — use a security group +- id: AZ-PG-003 + severity: required + description: Enable diagnostic settings for PostgreSQL audit and slow query logs + rationale: PostgreSQL logs track queries, connections, and errors for troubleshooting and compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for PostgreSQL diagnostic logs + targets: + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + resource "azapi_resource" "pg_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-postgresql" + parent_id = azapi_resource.pg_flexible.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "PostgreSQLLogs" + enabled = true + }, + { + category = "PostgreSQLFlexSessions" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource pgDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-postgresql' + scope: pgFlexible + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'PostgreSQLLogs' + enabled: true + } + { + category: 'PostgreSQLFlexSessions' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not disable PostgreSQLLogs in production +- id: AZ-PG-004 + severity: recommended + description: Enable zone-redundant high availability for production databases + rationale: Zone-redundant HA provides automatic failover with near-zero data loss across zones + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # Set highAvailability.mode = "ZoneRedundant" in server properties + # See PG-001 terraform_pattern for full example + bicep_pattern: | + // Set highAvailability.mode: 'ZoneRedundant' in server properties + // See PG-001 bicep_pattern for full example + prohibitions: + - Do not use SameZone HA for production — it does not protect against zone failures +patterns: +- name: PostgreSQL Flexible Server with Entra auth and VNet integration + description: Production PostgreSQL with Entra-only auth, VNet integration, HA, and diagnostics + example: | + # See PG-001 through PG-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not expose PostgreSQL to the public internet + instead: Use VNet integration with delegated subnet or private endpoints +- description: Do not use password authentication when Entra auth is available + instead: Set passwordAuth to Disabled and use Entra authentication +references: +- title: PostgreSQL Flexible Server documentation + url: https://learn.microsoft.com/azure/postgresql/flexible-server/overview +- title: Entra authentication for PostgreSQL + url: https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-azure-ad-authentication diff --git a/azext_prototype/governance/policies/azure/data/recovery-services.policy.yaml b/azext_prototype/governance/policies/azure/data/recovery-services.policy.yaml new file mode 100644 index 0000000..44abd15 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/recovery-services.policy.yaml @@ -0,0 +1,421 @@ +kind: policy +domain: azure-data +description: Governance policies for Recovery Services +last_updated: '2026-03-27' +rules: +- id: AZ-RSV-001 + severity: required + description: Deploy Recovery Services vault with geo-redundant storage, soft delete, and immutability + rationale: GRS protects against regional disasters; soft delete prevents accidental data loss; immutability prevents ransomware + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01 + name: daily-vm-policy + description: Backup schedule and retention policy defining RPO and recovery tiers + - type: Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01 + name: protected-vm + description: Protected item registering a VM or resource for backup in the vault + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-recovery-vault + description: Private endpoint for Recovery Services vault with groupId 'AzureBackup' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.{region}.backup.windowsazure.com + description: Private DNS zone for Recovery Services vault backup endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-recovery-vault + description: Diagnostic settings routing backup job and alert logs to Log Analytics + targets: + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + bicep_pattern: | + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + prohibitions: + - Do not disable soft delete — backup data cannot be recovered after deletion + - Do not disable enhanced security (MUA) — it protects against unauthorized backup modifications + - Do not enable publicNetworkAccess — use private endpoints + - Do not set immutability to Disabled without explicit business justification +- id: AZ-RSV-002 + severity: required + description: Configure storage replication as geo-redundant before protecting any items + rationale: Storage replication cannot be changed after backup items are registered; GRS is required for DR + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - Do not use LocallyRedundant for production — data loss on regional failure + - Do not register backup items before setting storage replication — it cannot be changed later +- id: AZ-RSV-003 + severity: required + description: Create backup policies with daily backups and appropriate retention tiers + rationale: Backup policies define RPO, RTO, and retention compliance — they must match DR requirements + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.RecoveryServices/vaults@2024-04-01 + name: recovery-vault + description: Parent Recovery Services vault that owns this backup policy + targets: + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = var.policy_name + parent_id = azapi_resource.recovery_vault.id + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + policyType = "V2" + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicyV2" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] + dailySchedule = { + scheduleRunTimes = ["2024-01-01T02:00:00Z"] + } + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Daily" + retentionScheduleDaily = { + daysOfTheMonth = [ + { + date = 1 + isLast = false + } + ] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + bicep_pattern: | + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: policyName + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + policyType: 'V2' + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicyV2' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + dailySchedule: { + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Daily' + retentionScheduleDaily: { + daysOfTheMonth: [ + { + date: 1 + isLast: false + } + ] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + prohibitions: + - Do not set daily retention below 7 days for production + - Do not skip weekly or monthly retention for compliance-regulated workloads +- id: AZ-RSV-004 + severity: recommended + description: Create private endpoint for Recovery Services vault + rationale: Private endpoint ensures all backup traffic stays on the Azure backbone + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.{region}.backup.windowsazure.com + description: Private DNS zone for Recovery Services vault backup endpoint + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.blob.core.windows.net + description: Private DNS zone for backup data storage blob endpoint + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.queue.core.windows.net + description: Private DNS zone for backup communication queue endpoint + targets: + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + resource "azapi_resource" "rsv_pe" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.recovery_vault_name}-pe" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.recovery_vault_name}-backup" + properties = { + privateLinkServiceId = azapi_resource.recovery_vault.id + groupIds = ["AzureBackup"] + } + } + ] + } + } + } + bicep_pattern: | + resource rsvPe 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${recoveryVaultName}-pe' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${recoveryVaultName}-backup' + properties: { + privateLinkServiceId: recoveryVault.id + groupIds: ['AzureBackup'] + } + } + ] + } + } + prohibitions: + - Do not skip DNS zone configuration — backup operations require multiple DNS zones +- id: AZ-RSV-005 + severity: recommended + description: Enable diagnostic settings for Recovery Services vault + rationale: Monitor backup job status, restore operations, and policy compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Recovery Services diagnostic logs + targets: + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + resource "azapi_resource" "rsv_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-recovery-vault" + parent_id = azapi_resource.recovery_vault.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "CoreAzureBackup" + enabled = true + }, + { + category = "AddonAzureBackupJobs" + enabled = true + }, + { + category = "AddonAzureBackupAlerts" + enabled = true + }, + { + category = "AddonAzureBackupPolicy" + enabled = true + }, + { + category = "AddonAzureBackupStorage" + enabled = true + }, + { + category = "AddonAzureBackupProtectedInstance" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource rsvDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-recovery-vault' + scope: recoveryVault + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'CoreAzureBackup' + enabled: true + } + { + category: 'AddonAzureBackupJobs' + enabled: true + } + { + category: 'AddonAzureBackupAlerts' + enabled: true + } + { + category: 'AddonAzureBackupPolicy' + enabled: true + } + { + category: 'AddonAzureBackupStorage' + enabled: true + } + { + category: 'AddonAzureBackupProtectedInstance' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit AddonAzureBackupJobs logs — they are essential for monitoring backup success rates +patterns: +- name: Recovery Services vault with GRS, soft delete, and private endpoint + description: Production Recovery Services vault with geo-redundancy, immutability, and private connectivity + example: | + # See RSV-001 through RSV-005 for complete azapi_resource patterns +anti_patterns: +- description: Do not use locally redundant storage for production Recovery Services vaults + instead: Use GeoRedundant storage and enable cross-region restore +- description: Do not disable soft delete or enhanced security + instead: Keep both enabled for ransomware protection and accidental deletion recovery +references: +- title: Recovery Services vault documentation + url: https://learn.microsoft.com/azure/backup/backup-azure-recovery-services-vault-overview +- title: Recovery Services vault security + url: https://learn.microsoft.com/azure/backup/security-overview diff --git a/azext_prototype/governance/policies/azure/data/redis-cache.policy.yaml b/azext_prototype/governance/policies/azure/data/redis-cache.policy.yaml new file mode 100644 index 0000000..6b72c20 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/redis-cache.policy.yaml @@ -0,0 +1,283 @@ +kind: policy +domain: azure-data +description: Governance policies for Redis Cache +last_updated: '2026-03-27' +rules: +- id: AZ-RED-001 + severity: required + description: Deploy Azure Cache for Redis with Premium or Enterprise SKU, TLS 1.2, and public access disabled + rationale: Premium/Enterprise SKUs support VNet injection, clustering, and data persistence; TLS 1.2 secures in-transit + data + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-redis + description: Private endpoint for Redis Cache with groupId 'redisCache' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.redis.cache.windows.net + description: Private DNS zone for Redis Cache private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-redis + description: Diagnostic settings routing Redis metrics and connection logs to Log Analytics + - type: Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01 + name: worker-data-access + description: Data-plane access policy assignment for managed identity (NOT standard RBAC) + terraform_pattern: | + resource "azapi_resource" "redis_data_access_policy" { + type = "Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01" + name = "worker-data-access" + parent_id = azapi_resource.redis_cache.id + body = { + properties = { + accessPolicyName = "Data Owner" + objectId = var.managed_identity_principal_id + objectIdAlias = "worker-identity" + } + } + } + targets: + - services: + - Microsoft.Cache/redis + terraform_pattern: | + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = var.redis_capacity + } + enableNonSslPort = false + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + redisVersion = "6" + redisConfiguration = { + "aad-enabled" = "true" + "maxmemory-policy" = "volatile-lru" + "maxfragmentationmemory-reserved" = "125" + "maxmemory-reserved" = "125" + } + replicasPerMaster = 1 + replicasPerPrimary = 1 + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + identity: { + type: 'SystemAssigned' + } + zones: ['1', '2', '3'] + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: redisCapacity + } + enableNonSslPort: false + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + redisVersion: '6' + redisConfiguration: { + 'maxmemory-policy': 'volatile-lru' + 'maxfragmentationmemory-reserved': '125' + 'maxmemory-reserved': '125' + } + replicasPerMaster: 1 + replicasPerPrimary: 1 + } + } + prohibitions: + - Do not use Basic or Standard SKU for production — they lack clustering, persistence, and VNet support + - Do not enable the non-SSL port (6379) — all connections must use TLS + - Do not enable publicNetworkAccess — use private endpoints + - Do not allow TLS versions below 1.2 + - Do not use access keys for application authentication when Microsoft Entra is available + - When Microsoft Entra (AAD) auth is enabled, accessKeys are NOT available. NEVER output or reference redis access keys + or connection strings. + - NEVER use Microsoft.Authorization/roleAssignments for Redis data-plane access — use Microsoft.Cache/redis/accessPolicyAssignments + instead +- id: AZ-RED-002 + severity: required + description: Disable the non-SSL port and enforce TLS 1.2 for all connections + rationale: Port 6379 sends data in plaintext; all Redis traffic must be encrypted in transit + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: [] + targets: + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # Set enableNonSslPort = false and minimumTlsVersion = "1.2" + # See RED-001 terraform_pattern for full example + bicep_pattern: | + // Set enableNonSslPort: false and minimumTlsVersion: '1.2' + // See RED-001 bicep_pattern for full example + prohibitions: + - Do not set enableNonSslPort to true + - Do not set minimumTlsVersion below 1.2 +- id: AZ-RED-003 + severity: recommended + description: Use Microsoft Entra authentication instead of access keys + rationale: Entra auth eliminates shared key management and supports fine-grained RBAC + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Cache/redis/accessPolicyAssignments@2024-03-01 + name: app-data-access + description: Data Owner or Data Contributor access policy for managed identity (NOT standard RBAC) + targets: + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # Entra auth is configured via redisConfiguration and RBAC + # Set aad-enabled = "true" in redisConfiguration + resource "azapi_resource" "redis_entra" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = var.redis_capacity + } + enableNonSslPort = false + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + redisConfiguration = { + "aad-enabled" = "true" + "maxmemory-policy" = "volatile-lru" + } + } + } + } + bicep_pattern: | + // Set aad-enabled to true in redisConfiguration + resource redisEntra 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: redisCapacity + } + enableNonSslPort: false + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + redisConfiguration: { + 'aad-enabled': 'true' + 'maxmemory-policy': 'volatile-lru' + } + } + } + prohibitions: + - Do not distribute Redis access keys to applications — use Entra authentication + - NEVER use Microsoft.Authorization/roleAssignments for Redis data-plane access — use Microsoft.Cache/redis/accessPolicyAssignments + instead +- id: AZ-RED-004 + severity: recommended + description: Enable diagnostic settings for Redis cache metrics and connection logs + rationale: Monitor cache hit ratio, connected clients, memory usage, and server load + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Redis Cache diagnostic data + targets: + - services: + - Microsoft.Cache/redis + terraform_pattern: | + resource "azapi_resource" "redis_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-redis" + parent_id = azapi_resource.redis_cache.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "ConnectedClientList" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource redisDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-redis' + scope: redisCache + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'ConnectedClientList' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit AllMetrics — cache hit ratio and memory usage are critical for performance tuning +patterns: +- name: Premium Redis with private endpoint and Entra auth + description: Zone-redundant Premium Redis with TLS 1.2, private endpoint, and Entra authentication + example: | + # See RED-001 through RED-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use Basic or Standard SKU for production workloads + instead: Use Premium or Enterprise SKU for clustering, persistence, and VNet support +- description: Do not enable the non-SSL port + instead: 'Set enableNonSslPort: false and enforce TLS 1.2' +references: +- title: Azure Cache for Redis documentation + url: https://learn.microsoft.com/azure/azure-cache-for-redis/cache-overview +- title: Redis security best practices + url: https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-security diff --git a/azext_prototype/governance/policies/azure/data/service-bus.policy.yaml b/azext_prototype/governance/policies/azure/data/service-bus.policy.yaml new file mode 100644 index 0000000..a8d4485 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/service-bus.policy.yaml @@ -0,0 +1,299 @@ +kind: policy +domain: azure-data +description: Governance policies for Service Bus +last_updated: '2026-03-27' +rules: +- id: AZ-SB-001 + severity: required + description: Deploy Service Bus namespace with Premium SKU, TLS 1.2, local auth disabled, and public access off + rationale: Premium SKU provides VNet integration, zone redundancy, and dedicated capacity; local auth bypass RBAC + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-servicebus + description: Private endpoint for Service Bus namespace with groupId 'namespace' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.servicebus.windows.net + description: Private DNS zone for Service Bus private endpoint resolution + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Azure Service Bus Data Sender/Receiver + description: Data Sender (69a216fc) and Data Receiver (4f6d3b9b) RBAC roles for managed identity + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-servicebus + description: Diagnostic settings routing operational and audit logs to Log Analytics + targets: + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + resource "azapi_resource" "servicebus_namespace" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.sb_namespace_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = var.messaging_units + } + properties = { + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + zoneRedundant = true + premiumMessagingPartitions = 1 + } + } + } + bicep_pattern: | + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: sbNamespaceName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Premium' + tier: 'Premium' + capacity: messagingUnits + } + properties: { + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + zoneRedundant: true + premiumMessagingPartitions: 1 + } + } + prohibitions: + - Do not use Basic or Standard SKU for production — they lack VNet integration, zone redundancy, and message sessions + - Do not enable publicNetworkAccess — use private endpoints + - Do not enable local auth (SAS keys) — use Entra RBAC + - Do not allow TLS versions below 1.2 + - When disableLocalAuth = true, SAS keys and connection strings are NOT available. NEVER output primaryConnectionString + or use listKeys. + - NEVER use 'Service Bus Contributor' for data access — use Data Sender/Receiver roles +- id: AZ-SB-002 + severity: required + description: Create queues and topics with dead-letter and duplicate detection enabled + rationale: Dead-letter queues capture failed messages for investigation; duplicate detection prevents reprocessing + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: [] + targets: + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + resource "azapi_resource" "sb_queue" { + type = "Microsoft.ServiceBus/namespaces/queues@2024-01-01" + name = var.queue_name + parent_id = azapi_resource.servicebus_namespace.id + body = { + properties = { + maxSizeInMegabytes = 5120 + requiresDuplicateDetection = true + duplicateDetectionHistoryTimeWindow = "PT10M" + requiresSession = false + deadLetteringOnMessageExpiration = true + maxDeliveryCount = 10 + lockDuration = "PT1M" + defaultMessageTimeToLive = "P14D" + enableBatchedOperations = true + } + } + } + bicep_pattern: | + resource sbQueue 'Microsoft.ServiceBus/namespaces/queues@2024-01-01' = { + parent: serviceBusNamespace + name: queueName + properties: { + maxSizeInMegabytes: 5120 + requiresDuplicateDetection: true + duplicateDetectionHistoryTimeWindow: 'PT10M' + requiresSession: false + deadLetteringOnMessageExpiration: true + maxDeliveryCount: 10 + lockDuration: 'PT1M' + defaultMessageTimeToLive: 'P14D' + enableBatchedOperations: true + } + } + prohibitions: + - Do not set maxDeliveryCount to 1 — transient failures will immediately dead-letter messages + - Do not disable deadLetteringOnMessageExpiration — expired messages will be silently lost +- id: AZ-SB-003 + severity: required + description: Create topic subscriptions with dead-letter and appropriate filters + rationale: Subscriptions without filters receive all messages; dead-letter captures failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: [] + targets: + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + resource "azapi_resource" "sb_topic" { + type = "Microsoft.ServiceBus/namespaces/topics@2024-01-01" + name = var.topic_name + parent_id = azapi_resource.servicebus_namespace.id + body = { + properties = { + maxSizeInMegabytes = 5120 + requiresDuplicateDetection = true + duplicateDetectionHistoryTimeWindow = "PT10M" + defaultMessageTimeToLive = "P14D" + enableBatchedOperations = true + } + } + } + + resource "azapi_resource" "sb_subscription" { + type = "Microsoft.ServiceBus/namespaces/topics/subscriptions@2024-01-01" + name = var.subscription_name + parent_id = azapi_resource.sb_topic.id + body = { + properties = { + maxDeliveryCount = 10 + lockDuration = "PT1M" + deadLetteringOnMessageExpiration = true + deadLetteringOnFilterEvaluationExceptions = true + defaultMessageTimeToLive = "P14D" + enableBatchedOperations = true + } + } + } + bicep_pattern: | + resource sbTopic 'Microsoft.ServiceBus/namespaces/topics@2024-01-01' = { + parent: serviceBusNamespace + name: topicName + properties: { + maxSizeInMegabytes: 5120 + requiresDuplicateDetection: true + duplicateDetectionHistoryTimeWindow: 'PT10M' + defaultMessageTimeToLive: 'P14D' + enableBatchedOperations: true + } + } + + resource sbSubscription 'Microsoft.ServiceBus/namespaces/topics/subscriptions@2024-01-01' = { + parent: sbTopic + name: subscriptionName + properties: { + maxDeliveryCount: 10 + lockDuration: 'PT1M' + deadLetteringOnMessageExpiration: true + deadLetteringOnFilterEvaluationExceptions: true + defaultMessageTimeToLive: 'P14D' + enableBatchedOperations: true + } + } + prohibitions: + - Do not disable deadLetteringOnFilterEvaluationExceptions — filter errors will silently drop messages +- id: AZ-SB-004 + severity: recommended + description: Enable diagnostic settings for Service Bus namespace + rationale: Monitor message counts, throttled requests, and dead-letter queue depth + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Service Bus diagnostic logs + targets: + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + resource "azapi_resource" "sb_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-service-bus" + parent_id = azapi_resource.servicebus_namespace.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "OperationalLogs" + enabled = true + }, + { + category = "VNetAndIPFilteringLogs" + enabled = true + }, + { + category = "RuntimeAuditLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource sbDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-service-bus' + scope: serviceBusNamespace + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'OperationalLogs' + enabled: true + } + { + category: 'VNetAndIPFilteringLogs' + enabled: true + } + { + category: 'RuntimeAuditLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit RuntimeAuditLogs — they track authentication and authorization events +patterns: +- name: Premium Service Bus with Entra RBAC and private endpoint + description: Production Service Bus with local auth disabled, private endpoint, and dead-letter queues + example: | + # See SB-001 through SB-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use SAS keys for Service Bus authentication + instead: Disable local auth and use Entra RBAC with managed identity +- description: Do not use Basic or Standard SKU for production + instead: Use Premium SKU for VNet integration, zone redundancy, and message sessions +references: +- title: Service Bus documentation + url: https://learn.microsoft.com/azure/service-bus-messaging/service-bus-messaging-overview +- title: Service Bus Premium tier + url: https://learn.microsoft.com/azure/service-bus-messaging/service-bus-premium-messaging diff --git a/azext_prototype/governance/policies/azure/data/stream-analytics.policy.yaml b/azext_prototype/governance/policies/azure/data/stream-analytics.policy.yaml new file mode 100644 index 0000000..c8a81f1 --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/stream-analytics.policy.yaml @@ -0,0 +1,288 @@ +kind: policy +domain: azure-data +description: Governance policies for Stream Analytics +last_updated: '2026-03-27' +rules: +- id: AZ-ASA-001 + severity: required + description: Deploy Stream Analytics job with Standard SKU, managed identity, and secure networking + rationale: Managed identity eliminates connection strings; Standard SKU supports production workloads + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Storage/storageAccounts@2023-01-01 + name: st-asa-checkpoint + description: Storage account for Stream Analytics job checkpointing and state storage + - type: Microsoft.StreamAnalytics/streamingJobs/inputs@2021-10-01-preview + name: asa-input + description: Input binding connecting the job to its event source (Event Hub, IoT Hub, etc.) + - type: Microsoft.StreamAnalytics/streamingJobs/outputs@2021-10-01-preview + name: asa-output + description: Output binding connecting the job to its destination (Cosmos DB, SQL, Blob, etc.) + - type: Microsoft.StreamAnalytics/clusters@2020-03-01 + name: asa-cluster + description: Dedicated cluster for VNet isolation of Stream Analytics jobs + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-asa + description: Diagnostic settings routing execution and authoring logs to Log Analytics + targets: + - services: + - Microsoft.StreamAnalytics/streamingJobs + terraform_pattern: | + resource "azapi_resource" "stream_analytics_job" { + type = "Microsoft.StreamAnalytics/streamingJobs@2021-10-01-preview" + name = var.asa_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + sku = { + name = "Standard" + } + compatibilityLevel = "1.2" + dataLocale = "en-US" + eventsLateArrivalMaxDelayInSeconds = 5 + eventsOutOfOrderMaxDelayInSeconds = 0 + eventsOutOfOrderPolicy = "Adjust" + outputErrorPolicy = "Stop" + contentStoragePolicy = "JobStorageAccount" + jobStorageAccount = { + authenticationMode = "Msi" + accountName = var.storage_account_name + accountKey = null + } + cluster = var.asa_cluster_id != null ? { + id = var.asa_cluster_id + } : null + } + } + } + bicep_pattern: | + resource streamAnalyticsJob 'Microsoft.StreamAnalytics/streamingJobs@2021-10-01-preview' = { + name: asaName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + sku: { + name: 'Standard' + } + compatibilityLevel: '1.2' + dataLocale: 'en-US' + eventsLateArrivalMaxDelayInSeconds: 5 + eventsOutOfOrderMaxDelayInSeconds: 0 + eventsOutOfOrderPolicy: 'Adjust' + outputErrorPolicy: 'Stop' + contentStoragePolicy: 'JobStorageAccount' + jobStorageAccount: { + authenticationMode: 'Msi' + accountName: storageAccountName + accountKey: null + } + } + } + prohibitions: + - Do not use connection strings with account keys — use managed identity authentication + - Do not set outputErrorPolicy to Drop in production — errors should halt processing for investigation + - Do not use compatibility level below 1.2 +- id: AZ-ASA-002 + severity: required + description: Use managed identity for all input and output connections + rationale: Connection strings with keys are insecure and hard to rotate; managed identity is zero-credential + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: ASA Data Reader/Sender + description: Data reader/sender roles granting ASA managed identity access to input/output resources + targets: + - services: + - Microsoft.StreamAnalytics/streamingJobs + terraform_pattern: | + resource "azapi_resource" "asa_input" { + type = "Microsoft.StreamAnalytics/streamingJobs/inputs@2021-10-01-preview" + name = var.input_name + parent_id = azapi_resource.stream_analytics_job.id + body = { + properties = { + type = "Stream" + datasource = { + type = "Microsoft.EventHub/EventHub" + properties = { + serviceBusNamespace = var.eh_namespace + eventHubName = var.eventhub_name + consumerGroupName = var.consumer_group + authenticationMode = "Msi" + } + } + serialization = { + type = "Json" + properties = { + encoding = "UTF8" + } + } + } + } + } + bicep_pattern: | + resource asaInput 'Microsoft.StreamAnalytics/streamingJobs/inputs@2021-10-01-preview' = { + parent: streamAnalyticsJob + name: inputName + properties: { + type: 'Stream' + datasource: { + type: 'Microsoft.EventHub/EventHub' + properties: { + serviceBusNamespace: ehNamespace + eventHubName: eventhubName + consumerGroupName: consumerGroup + authenticationMode: 'Msi' + } + } + serialization: { + type: 'Json' + properties: { + encoding: 'UTF8' + } + } + } + } + prohibitions: + - Do not use ConnectionString authentication mode — use Msi + - Do not store Event Hub or Service Bus connection strings in job configuration +- id: AZ-ASA-003 + severity: recommended + description: Deploy Stream Analytics in a dedicated cluster for VNet isolation + rationale: Dedicated clusters support private endpoints and VNet integration for network isolation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-asa-cluster + description: Private endpoints connecting the ASA cluster to input and output resources + targets: + - services: + - Microsoft.StreamAnalytics/streamingJobs + terraform_pattern: | + resource "azapi_resource" "asa_cluster" { + type = "Microsoft.StreamAnalytics/clusters@2020-03-01" + name = var.cluster_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Default" + capacity = 36 + } + properties = {} + } + } + bicep_pattern: | + resource asaCluster 'Microsoft.StreamAnalytics/clusters@2020-03-01' = { + name: clusterName + location: location + sku: { + name: 'Default' + capacity: 36 + } + properties: {} + } + prohibitions: + - Do not set capacity below 36 SUs — minimum for dedicated cluster +- id: AZ-ASA-004 + severity: recommended + description: Enable diagnostic settings for Stream Analytics job metrics and logs + rationale: Monitor watermark delay, input/output events, and runtime errors + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Stream Analytics diagnostic data + targets: + - services: + - Microsoft.StreamAnalytics/streamingJobs + terraform_pattern: | + resource "azapi_resource" "asa_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-stream-analytics" + parent_id = azapi_resource.stream_analytics_job.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "Execution" + enabled = true + }, + { + category = "Authoring" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource asaDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-stream-analytics' + scope: streamAnalyticsJob + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'Execution' + enabled: true + } + { + category: 'Authoring' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit Execution logs — they track runtime errors and processing issues +patterns: +- name: Stream Analytics job with managed identity and diagnostics + description: Production ASA job using managed identity for all connections + example: | + # See ASA-001 through ASA-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use connection strings for input/output authentication + instead: 'Use managed identity (authenticationMode: Msi) for all data connections' +- description: Do not set outputErrorPolicy to Drop without explicit error handling + instead: Use Stop policy and configure alerts on error metrics +references: +- title: Stream Analytics documentation + url: https://learn.microsoft.com/azure/stream-analytics/stream-analytics-introduction +- title: Stream Analytics managed identity + url: https://learn.microsoft.com/azure/stream-analytics/stream-analytics-managed-identities-overview diff --git a/azext_prototype/governance/policies/azure/data/synapse-workspace.policy.yaml b/azext_prototype/governance/policies/azure/data/synapse-workspace.policy.yaml new file mode 100644 index 0000000..eeec34d --- /dev/null +++ b/azext_prototype/governance/policies/azure/data/synapse-workspace.policy.yaml @@ -0,0 +1,403 @@ +kind: policy +domain: azure-data +description: Governance policies for Synapse Workspace +last_updated: '2026-03-27' +rules: +- id: AZ-SYN-001 + severity: required + description: Deploy Synapse Workspace with managed VNet, managed identity, and public access disabled + rationale: Managed VNet isolates Spark/pipeline traffic; managed identity eliminates credential management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Storage/storageAccounts@2023-01-01 + name: st-synapse-datalake + description: ADLS Gen2 storage account serving as the default data lake for Synapse + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-synapse-sql, pe-synapse-sqlod, pe-synapse-dev + description: Private endpoints for Synapse SQL, SqlOnDemand, and Dev endpoints + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.sql.azuresynapse.net + description: Private DNS zones for Synapse SQL, Dev, and workspace endpoint resolution + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-cmk + description: Key Vault storing customer-managed encryption keys for Synapse workspace + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-synapse + description: Diagnostic settings routing RBAC, gateway, and pipeline logs to Log Analytics + targets: + - services: + - Microsoft.Synapse/workspaces + terraform_pattern: | + resource "azapi_resource" "synapse_workspace" { + type = "Microsoft.Synapse/workspaces@2021-06-01" + name = var.synapse_name + location = var.location + parent_id = var.resource_group_id + identity { + type = "SystemAssigned" + } + body = { + properties = { + defaultDataLakeStorage = { + accountUrl = "https://${var.storage_account_name}.dfs.core.windows.net" + filesystem = var.filesystem_name + resourceId = var.storage_account_id + } + managedVirtualNetwork = "default" + managedResourceGroupName = var.managed_rg_name + publicNetworkAccess = "Disabled" + preventDataExfiltration = true + sqlAdministratorLogin = var.sql_admin_login + sqlAdministratorLoginPassword = var.sql_admin_password + managedVirtualNetworkSettings = { + preventDataExfiltration = true + allowedAadTenantIdsForLinking = [var.tenant_id] + } + encryption = { + cmk = { + key = { + name = "default" + keyVaultUrl = var.cmk_key_url + } + } + } + } + } + } + bicep_pattern: | + resource synapseWorkspace 'Microsoft.Synapse/workspaces@2021-06-01' = { + name: synapseName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + defaultDataLakeStorage: { + accountUrl: 'https://${storageAccountName}.dfs.core.windows.net' + filesystem: filesystemName + resourceId: storageAccountId + } + managedVirtualNetwork: 'default' + managedResourceGroupName: managedRgName + publicNetworkAccess: 'Disabled' + preventDataExfiltration: true + sqlAdministratorLogin: sqlAdminLogin + sqlAdministratorLoginPassword: sqlAdminPassword + managedVirtualNetworkSettings: { + preventDataExfiltration: true + allowedAadTenantIdsForLinking: [tenantId] + } + encryption: { + cmk: { + key: { + name: 'default' + keyVaultUrl: cmkKeyUrl + } + } + } + } + } + prohibitions: + - Do not enable publicNetworkAccess — use private endpoints + - Do not disable preventDataExfiltration — it allows data to leave the managed VNet + - Do not hardcode sqlAdministratorLoginPassword in templates — use Key Vault references + - Do not skip managed VNet configuration — pipelines and Spark will use public internet +- id: AZ-SYN-002 + severity: required + description: Configure Entra-only authentication for Synapse SQL pools + rationale: SQL auth with passwords is less secure than Entra identity-based authentication + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Synapse/workspaces/administrators@2021-06-01 + name: activeDirectory + description: Entra ID admin assignment for Synapse workspace SQL pools + targets: + - services: + - Microsoft.Synapse/workspaces + terraform_pattern: | + resource "azapi_resource" "synapse_aad_admin" { + type = "Microsoft.Synapse/workspaces/azureADOnlyAuthentications@2021-06-01" + name = "default" + parent_id = azapi_resource.synapse_workspace.id + body = { + properties = { + azureADOnlyAuthentication = true + } + } + } + bicep_pattern: | + resource synapseAadAdmin 'Microsoft.Synapse/workspaces/azureADOnlyAuthentications@2021-06-01' = { + parent: synapseWorkspace + name: 'default' + properties: { + azureADOnlyAuthentication: true + } + } + prohibitions: + - Do not use SQL authentication in production — use Entra-only auth +- id: AZ-SYN-003 + severity: required + description: Create private endpoints for all Synapse endpoints (SQL, SqlOnDemand, Dev) + rationale: Synapse has three endpoints that all need private connectivity for full isolation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.sql.azuresynapse.net + description: Private DNS zone for Synapse SQL endpoint resolution + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.dev.azuresynapse.net + description: Private DNS zone for Synapse Dev (Studio) endpoint resolution + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azuresynapse.net + description: Private DNS zone for Synapse workspace management endpoint resolution + - type: Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-04-01 + name: default + description: DNS zone group registering Synapse private endpoint DNS records + targets: + - services: + - Microsoft.Synapse/workspaces + terraform_pattern: | + resource "azapi_resource" "synapse_pe_sql" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.synapse_name}-pe-sql" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.synapse_name}-sql" + properties = { + privateLinkServiceId = azapi_resource.synapse_workspace.id + groupIds = ["Sql"] + } + } + ] + } + } + } + + resource "azapi_resource" "synapse_pe_sqlondemand" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.synapse_name}-pe-sqlondemand" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.synapse_name}-sqlondemand" + properties = { + privateLinkServiceId = azapi_resource.synapse_workspace.id + groupIds = ["SqlOnDemand"] + } + } + ] + } + } + } + + resource "azapi_resource" "synapse_pe_dev" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "${var.synapse_name}-pe-dev" + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "${var.synapse_name}-dev" + properties = { + privateLinkServiceId = azapi_resource.synapse_workspace.id + groupIds = ["Dev"] + } + } + ] + } + } + } + bicep_pattern: | + resource synapsePeSql 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${synapseName}-pe-sql' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${synapseName}-sql' + properties: { + privateLinkServiceId: synapseWorkspace.id + groupIds: ['Sql'] + } + } + ] + } + } + + resource synapsePeSqlOnDemand 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${synapseName}-pe-sqlondemand' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${synapseName}-sqlondemand' + properties: { + privateLinkServiceId: synapseWorkspace.id + groupIds: ['SqlOnDemand'] + } + } + ] + } + } + + resource synapsePeDev 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: '${synapseName}-pe-dev' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: '${synapseName}-dev' + properties: { + privateLinkServiceId: synapseWorkspace.id + groupIds: ['Dev'] + } + } + ] + } + } + prohibitions: + - Do not skip any of the three private endpoints — partial coverage leaves endpoints exposed +- id: AZ-SYN-004 + severity: recommended + description: Enable diagnostic settings for Synapse workspace audit logs + rationale: Audit logs track user activities, SQL queries, and pipeline executions + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Synapse workspace diagnostic logs + targets: + - services: + - Microsoft.Synapse/workspaces + terraform_pattern: | + resource "azapi_resource" "synapse_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-synapse" + parent_id = azapi_resource.synapse_workspace.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "SynapseRbacOperations" + enabled = true + }, + { + category = "GatewayApiRequests" + enabled = true + }, + { + category = "BuiltinSqlReqsEnded" + enabled = true + }, + { + category = "IntegrationPipelineRuns" + enabled = true + }, + { + category = "IntegrationActivityRuns" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource synapseDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-synapse' + scope: synapseWorkspace + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'SynapseRbacOperations' + enabled: true + } + { + category: 'GatewayApiRequests' + enabled: true + } + { + category: 'BuiltinSqlReqsEnded' + enabled: true + } + { + category: 'IntegrationPipelineRuns' + enabled: true + } + { + category: 'IntegrationActivityRuns' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not skip SynapseRbacOperations logs — they track permission changes +patterns: +- name: Synapse Workspace with managed VNet and private endpoints + description: Fully isolated Synapse workspace with CMK, managed VNet, and Entra auth + example: | + # See SYN-001 through SYN-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy Synapse without managed virtual network + instead: Enable managedVirtualNetwork to isolate Spark and pipeline traffic +- description: Do not use SQL authentication for Synapse SQL pools + instead: Enable Entra-only authentication via azureADOnlyAuthentications +references: +- title: Synapse Analytics security + url: https://learn.microsoft.com/azure/synapse-analytics/security/synapse-workspace-managed-vnet +- title: Synapse private endpoints + url: https://learn.microsoft.com/azure/synapse-analytics/security/synapse-workspace-managed-private-endpoints diff --git a/azext_prototype/governance/policies/azure/functions.policy.yaml b/azext_prototype/governance/policies/azure/functions.policy.yaml deleted file mode 100644 index acb680f..0000000 --- a/azext_prototype/governance/policies/azure/functions.policy.yaml +++ /dev/null @@ -1,81 +0,0 @@ -apiVersion: v1 -kind: policy -metadata: - name: functions - category: azure - services: [functions] - last_reviewed: "2026-02-01" - -rules: - - id: FN-001 - severity: required - description: "Use managed identity for accessing Azure resources from Functions" - rationale: "Eliminates connection strings and secrets in function configuration" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [functions] - require_config: [identity] - error_message: "Service '{service_name}' ({service_type}) missing managed identity configuration" - - - id: FN-002 - severity: required - description: "Store function app secrets in Key Vault with Key Vault references" - rationale: "App Settings plaintext secrets leak through Kudu, deployment logs, and ARM exports" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer] - - - id: FN-003 - severity: required - description: "Enforce HTTPS-only and minimum TLS 1.2" - rationale: "Same baseline as App Service — prevents cleartext transmission" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: FN-004 - severity: recommended - description: "Use Consumption plan for event-driven, variable workloads; Premium for VNET or sustained load" - rationale: "Consumption plan has cold starts but costs nothing at idle; Premium provides VNET integration" - applies_to: [cloud-architect, cost-analyst, biz-analyst] - - - id: FN-005 - severity: recommended - description: "Enable Application Insights for function monitoring and distributed tracing" - rationale: "Functions are inherently distributed — observability is critical for debugging" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent, app-developer] - - - id: FN-006 - severity: recommended - description: "Use durable functions or Service Bus for long-running orchestrations" - rationale: "Regular functions have a 5-10 minute timeout; durable functions handle complex workflows" - applies_to: [cloud-architect, app-developer, biz-analyst] - - - id: FN-007 - severity: required - description: "C# Azure Functions must use the isolated worker model (not in-process)" - rationale: "In-process model is deprecated; isolated worker provides better performance, dependency isolation, and long-term support" - applies_to: [cloud-architect, app-developer] - -patterns: - - name: "Function App with managed identity" - description: "Standard Function App deployment with identity and monitoring" - example: | - resource "azurerm_linux_function_app" "main" { - https_only = true - identity { - type = "SystemAssigned" - } - site_config { - minimum_tls_version = "1.2" - application_insights_connection_string = azurerm_application_insights.main.connection_string - } - } - -anti_patterns: - - description: "Do not store connection strings in Function App Settings as plaintext" - instead: "Use Key Vault references: @Microsoft.KeyVault(SecretUri=...)" - - description: "Do not use Consumption plan when VNET integration is required" - instead: "Use Premium plan (EP1+) or App Service plan for VNET-integrated functions" - -references: - - title: "Azure Functions security" - url: "https://learn.microsoft.com/azure/azure-functions/security-concepts" - - title: "Functions networking options" - url: "https://learn.microsoft.com/azure/azure-functions/functions-networking-options" diff --git a/azext_prototype/governance/policies/azure/identity/__init__.py b/azext_prototype/governance/policies/azure/identity/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/identity/managed-identity.policy.yaml b/azext_prototype/governance/policies/azure/identity/managed-identity.policy.yaml new file mode 100644 index 0000000..1b87339 --- /dev/null +++ b/azext_prototype/governance/policies/azure/identity/managed-identity.policy.yaml @@ -0,0 +1,127 @@ +kind: policy +domain: azure-identity +description: Governance policies for Managed Identity +last_updated: '2026-03-27' +rules: +- id: AZ-MI-001 + severity: required + description: Create User-Assigned Managed Identity for shared identity across services + rationale: User-assigned identities can be shared across multiple resources and survive resource recreation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ManagedIdentity/userAssignedIdentities + terraform_pattern: | + resource "azapi_resource" "user_assigned_identity" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview" + name = var.identity_name + location = var.location + parent_id = azapi_resource.resource_group.id + } + + output "identity_client_id" { + value = azapi_resource.user_assigned_identity.output.properties.clientId + } + + output "identity_principal_id" { + value = azapi_resource.user_assigned_identity.output.properties.principalId + } + + output "identity_resource_id" { + value = azapi_resource.user_assigned_identity.id + } + bicep_pattern: | + resource userAssignedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' = { + name: identityName + location: location + } + + output identityClientId string = userAssignedIdentity.properties.clientId + output identityPrincipalId string = userAssignedIdentity.properties.principalId + output identityResourceId string = userAssignedIdentity.id + prohibitions: + - NEVER use system-assigned identity as the sole identity for multi-resource architectures — use user-assigned for shared + access + - NEVER hardcode principal IDs — always reference the identity resource output +- id: AZ-MI-002 + severity: required + description: Use deterministic names for RBAC role assignments using uuidv5 + rationale: Role assignment names must be GUIDs; uuidv5 generates deterministic UUIDs from a namespace + name, ensuring idempotent + deployments + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ManagedIdentity/userAssignedIdentities + terraform_pattern: | + # Use uuidv5 for deterministic RBAC role assignment names + # uuidv5(namespace_uuid, name_string) is a Terraform built-in function + # Use the URL namespace UUID and a combination of resource IDs for uniqueness + resource "azapi_resource" "role_assignment" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("6ba7b811-9dad-11d1-80b4-00c04fd430c8", "${var.scope_resource_id}-${var.principal_id}-${var.role_definition_id}") + parent_id = var.scope_resource_id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/${var.role_definition_id}" + principalId = azapi_resource.user_assigned_identity.output.properties.principalId + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + // Use guid() with deterministic seed for Bicep role assignment names + resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: targetResource + name: guid(targetResource.id, userAssignedIdentity.id, roleDefinitionId) + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId) + principalId: userAssignedIdentity.properties.principalId + principalType: 'ServicePrincipal' + } + } + prohibitions: + - NEVER use uuid() for role assignment names — it generates a new random UUID every plan, causing unnecessary replacements + - NEVER use guid() in Terraform — it does not exist; use uuidv5() instead + - NEVER hardcode role assignment GUIDs as literal strings — always generate deterministically with uuidv5 +- id: AZ-MI-003 + severity: required + description: Always output client_id and principal_id from the identity module + rationale: 'Downstream resources need both IDs: client_id for SDK configuration, principal_id for RBAC assignments' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ManagedIdentity/userAssignedIdentities +- id: AZ-MI-004 + severity: recommended + description: Create one identity per logical application boundary + rationale: Sharing identity across all services simplifies RBAC management while maintaining security boundaries per application + applies_to: + - cloud-architect + targets: + - services: + - Microsoft.ManagedIdentity/userAssignedIdentities +patterns: +- name: User-Assigned Managed Identity with RBAC + description: Create identity and assign roles to target resources using deterministic names +anti_patterns: +- description: Do not use system-assigned identity when multiple resources need shared access + instead: Use user-assigned managed identity shared across the application boundary +- description: Do not use newGuid() for role assignment names + instead: 'Use guid() with deterministic seeds: guid(resourceId, identityId, roleDefId)' +- description: Do not create multiple identities for tightly coupled services in the same app + instead: Share one user-assigned identity per logical application +references: +- title: Managed identities best practices + url: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/managed-identity-best-practice-recommendations +- title: User-assigned managed identity + url: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities diff --git a/azext_prototype/governance/policies/azure/identity/resource-groups.policy.yaml b/azext_prototype/governance/policies/azure/identity/resource-groups.policy.yaml new file mode 100644 index 0000000..13398f1 --- /dev/null +++ b/azext_prototype/governance/policies/azure/identity/resource-groups.policy.yaml @@ -0,0 +1,115 @@ +kind: policy +domain: azure-identity +description: Governance policies for Resource Groups +last_updated: '2026-03-27' +rules: +- id: AZ-RG-001 + severity: required + description: Create Resource Group with required tags and location from variable + rationale: Tags enable cost tracking, ownership identification, and automated governance; location must be parameterized + for portability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Resources/resourceGroups + terraform_pattern: | + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + parent_id = "/subscriptions/${var.subscription_id}" + location = var.location + + tags = { + project = var.project_name + environment = var.environment + owner = var.owner + created_by = "azext-prototype" + } + + body = {} + } + bicep_pattern: | + targetScope = 'subscription' + + resource resourceGroup 'Microsoft.Resources/resourceGroups@2024-03-01' = { + name: resourceGroupName + location: location + tags: { + project: projectName + environment: environment + owner: owner + created_by: 'azext-prototype' + } + } + prohibitions: + - NEVER hardcode the location — always use a variable (var.location in Terraform, location parameter in Bicep) + - NEVER create a resource group without tags + - NEVER hardcode the resource group name — always use a variable +- id: AZ-RG-002 + severity: required + description: 'Include mandatory tags: project, environment, owner, created_by' + rationale: These tags are required for cost tracking, environment identification, ownership, and audit trail + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Resources/resourceGroups + prohibitions: + - NEVER omit the project tag — it identifies which POC this resource group belongs to + - NEVER omit the environment tag — it distinguishes dev/staging/prod resources + - NEVER omit the owner tag — it identifies who is responsible for the resource group +- id: AZ-RG-003 + severity: required + description: Set Bicep targetScope to subscription when creating resource groups + rationale: Resource groups are subscription-level resources; Bicep defaults to resourceGroup scope which cannot create resource + groups + applies_to: + - bicep-agent + targets: + - services: + - Microsoft.Resources/resourceGroups + prohibitions: + - NEVER omit targetScope = 'subscription' in the Bicep file that creates resource groups +- id: AZ-RG-004 + severity: recommended + description: 'Use naming convention: rg-{project}-{environment}-{location}' + rationale: Consistent naming enables automation, scripting, and resource identification + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Resources/resourceGroups +- id: AZ-RG-005 + severity: recommended + description: Create separate resource groups for different lifecycle boundaries + rationale: Shared resources (VNet, DNS, Key Vault) should be in a separate resource group from application resources to + avoid accidental deletion + applies_to: + - cloud-architect + targets: + - services: + - Microsoft.Resources/resourceGroups +patterns: +- name: Resource Group with tags + description: Standard resource group with required tags and parameterized location +anti_patterns: +- description: Do not hardcode resource group location + instead: Use a variable/parameter for location to enable multi-region deployment +- description: Do not create resource groups without tags + instead: Always include project, environment, owner, and created_by tags +- description: Do not put all resources in a single resource group + instead: Separate by lifecycle boundary — shared infrastructure vs application resources +references: +- title: Resource group design + url: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-setup-guide/organize-resources +- title: Tagging strategy + url: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-tagging +- title: Naming conventions + url: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-naming diff --git a/azext_prototype/governance/policies/azure/key-vault.policy.yaml b/azext_prototype/governance/policies/azure/key-vault.policy.yaml deleted file mode 100644 index 8bfb1fa..0000000 --- a/azext_prototype/governance/policies/azure/key-vault.policy.yaml +++ /dev/null @@ -1,75 +0,0 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: key-vault - category: azure - services: [key-vault] - last_reviewed: "2025-12-01" - -rules: - - id: KV-001 - severity: required - description: "Enable soft-delete and purge protection" - rationale: "Prevents accidental permanent deletion of secrets and keys" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [key-vault] - require_config: [soft_delete, purge_protection] - error_message: "Service '{service_name}' ({service_type}) missing {config_key}: true" - - - id: KV-002 - severity: required - description: "Use RBAC authorization model, not access policies" - rationale: "RBAC is the recommended model for fine-grained access control" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - scope: [key-vault] - require_config: [rbac_authorization] - error_message: "Service '{service_name}' ({service_type}) missing rbac_authorization: true" - - - id: KV-003 - severity: required - description: "Access Key Vault via managed identity, never service principal secrets" - rationale: "Managed identity removes credential management overhead" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - - - id: KV-004 - severity: recommended - description: "Enable diagnostic logging to Log Analytics" - rationale: "Audit trail for secret access and key operations" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [key-vault] - require_config: [diagnostics] - error_message: "Service '{service_name}' ({service_type}) missing diagnostics: true for Log Analytics" - - - id: KV-005 - severity: recommended - description: "Use private endpoints in production environments" - rationale: "Restricts Key Vault access to the virtual network" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [key-vault] - require_config: [private_endpoint] - error_message: "Service '{service_name}' ({service_type}) missing private_endpoint: true" - -patterns: - - name: "Key Vault with RBAC" - description: "Create Key Vault with RBAC authorization and role assignments" - example: | - resource "azurerm_key_vault" "main" { - enable_rbac_authorization = true - soft_delete_retention_days = 90 - purge_protection_enabled = true - } - -anti_patterns: - - description: "Do not use access policies for authorization" - instead: "Set enable_rbac_authorization = true and use role assignments" - - description: "Do not disable soft-delete" - instead: "Keep soft-delete enabled with at least 7-day retention" - -references: - - title: "Key Vault best practices" - url: "https://learn.microsoft.com/azure/key-vault/general/best-practices" diff --git a/azext_prototype/governance/policies/azure/management/__init__.py b/azext_prototype/governance/policies/azure/management/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/management/automation.policy.yaml b/azext_prototype/governance/policies/azure/management/automation.policy.yaml new file mode 100644 index 0000000..1744f30 --- /dev/null +++ b/azext_prototype/governance/policies/azure/management/automation.policy.yaml @@ -0,0 +1,217 @@ +kind: policy +domain: azure-management +description: Governance policies for Automation +last_updated: '2026-03-27' +rules: +- id: AZ-AUTO-001 + severity: required + description: Deploy Azure Automation account with managed identity, disabled public access, and encryption + rationale: Automation accounts execute privileged runbooks; managed identity eliminates Run As account credentials + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-automation + description: Private endpoint for Automation account to secure webhook and DSC endpoints + terraform_pattern: | + resource "azapi_resource" "pe_automation" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.automation_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "automation-connection" + properties = { + privateLinkServiceId = azapi_resource.automation.id + groupIds = ["DSCAndHybridWorker"] + } + } + ] + } + } + } + bicep_pattern: | + resource peAutomation 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${automationName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'automation-connection' + properties: { + privateLinkServiceId: automation.id + groupIds: ['DSCAndHybridWorker'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.azure-automation.net + description: Private DNS zone for Automation account private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-automation + description: Diagnostic settings to route job logs, DSC logs, and runbook output to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_automation" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.automation_name}" + parent_id = azapi_resource.automation.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagAutomation 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${automationName}' + scope: automation + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Automation Contributor + description: RBAC role assignment for automation account management + targets: + - services: + - Microsoft.Automation/automationAccounts + terraform_pattern: | + resource "azapi_resource" "automation" { + type = "Microsoft.Automation/automationAccounts@2023-11-01" + name = var.automation_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + sku = { + name = "Basic" + } + publicNetworkAccess = false + disableLocalAuth = true + encryption = { + keySource = "Microsoft.Automation" + } + } + } + } + bicep_pattern: | + resource automation 'Microsoft.Automation/automationAccounts@2023-11-01' = { + name: automationName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + sku: { + name: 'Basic' + } + publicNetworkAccess: false + disableLocalAuth: true + encryption: { + keySource: 'Microsoft.Automation' + } + } + } + prohibitions: + - Never use Run As accounts — they are deprecated; use managed identity + - Never hardcode credentials in runbook scripts or variables + - Never set disableLocalAuth to false — use Microsoft Entra authentication + - Never store secrets as plain-text Automation variables — use encrypted variables or Key Vault + - Never enable public network access without compensating network controls +- id: AZ-AUTO-002 + severity: required + description: Use managed identity for all runbook authentication instead of Run As accounts + rationale: Run As accounts use certificates that must be rotated; managed identity is automatic and auditable + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Automation/automationAccounts +- id: AZ-AUTO-003 + severity: recommended + description: Link Automation account to Log Analytics workspace for job log aggregation + rationale: Linked workspace enables centralized monitoring of runbook execution and failure analysis + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Automation/automationAccounts +- id: AZ-AUTO-004 + severity: recommended + description: Use encrypted Automation variables or Key Vault references for sensitive configuration + rationale: Plain-text variables are visible to account contributors; encrypted variables add a protection layer + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Automation/automationAccounts +patterns: +- name: Automation account with managed identity and private endpoint + description: Secure Automation account with no public access, managed identity, and Log Analytics integration +anti_patterns: +- description: Do not use Run As accounts for runbook authentication + instead: Use system-assigned managed identity with RBAC role assignments +- description: Do not store secrets in plain-text Automation variables + instead: Use encrypted variables or Key Vault references accessed via managed identity +references: +- title: Azure Automation documentation + url: https://learn.microsoft.com/azure/automation/overview +- title: Automation managed identity + url: https://learn.microsoft.com/azure/automation/automation-security-overview diff --git a/azext_prototype/governance/policies/azure/management/communication-services.policy.yaml b/azext_prototype/governance/policies/azure/management/communication-services.policy.yaml new file mode 100644 index 0000000..cb78a77 --- /dev/null +++ b/azext_prototype/governance/policies/azure/management/communication-services.policy.yaml @@ -0,0 +1,211 @@ +kind: policy +domain: azure-management +description: Governance policies for Communication Services +last_updated: '2026-03-27' +rules: +- id: AZ-ACS-001 + severity: required + description: Deploy Azure Communication Services with managed identity and disabled access key authentication + rationale: Access keys grant full control and cannot be scoped; managed identity with RBAC provides auditable access + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Communication/emailServices@2023-04-01 + name: email-service + description: Email Communication Service for email sending capabilities + terraform_pattern: | + resource "azapi_resource" "email_service" { + type = "Microsoft.Communication/emailServices@2023-04-01" + name = var.email_service_name + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + dataLocation = var.data_location + } + } + } + bicep_pattern: | + resource emailService 'Microsoft.Communication/emailServices@2023-04-01' = { + name: emailServiceName + location: 'global' + properties: { + dataLocation: dataLocation + } + } + - type: Microsoft.Communication/emailServices/domains@2023-04-01 + name: email-domain + description: Email domain with DKIM, SPF, and DMARC configuration for verified sending + terraform_pattern: | + resource "azapi_resource" "email_domain" { + type = "Microsoft.Communication/emailServices/domains@2023-04-01" + name = var.email_domain_name + location = "global" + parent_id = azapi_resource.email_service.id + + body = { + properties = { + domainManagement = "CustomerManaged" + userEngagementTracking = "Disabled" + } + } + } + bicep_pattern: | + resource emailDomain 'Microsoft.Communication/emailServices/domains@2023-04-01' = { + name: emailDomainName + parent: emailService + location: 'global' + properties: { + domainManagement: 'CustomerManaged' + userEngagementTracking: 'Disabled' + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-acs + description: Diagnostic settings for chat, SMS, voice, and email operation logs + terraform_pattern: | + resource "azapi_resource" "diag_acs" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.communication_name}" + parent_id = azapi_resource.communication.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagAcs 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${communicationName}' + scope: communication + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Communication Service Contributor + description: RBAC role assignment for ACS resource management + targets: + - services: + - Microsoft.Communication/communicationServices + terraform_pattern: | + resource "azapi_resource" "communication" { + type = "Microsoft.Communication/communicationServices@2023-04-01" + name = var.communication_name + location = "global" + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + dataLocation = var.data_location # "United States", "Europe", "UK", "Japan", etc. + } + } + } + bicep_pattern: | + resource communication 'Microsoft.Communication/communicationServices@2023-04-01' = { + name: communicationName + location: 'global' + identity: { + type: 'SystemAssigned' + } + properties: { + dataLocation: dataLocation + } + } + prohibitions: + - Never hardcode ACS access keys or connection strings in application code + - Never distribute access keys to client-side applications — use user access tokens + - Never use AzureManaged domains for production email — use CustomerManaged with verified domains + - Never enable userEngagementTracking without user consent (privacy regulations) + - Never skip data location selection — it determines data residency and compliance boundary +- id: AZ-ACS-002 + severity: required + description: Set dataLocation to match compliance requirements for data residency + rationale: Communication data (chat transcripts, call recordings) must reside in the correct geography for regulatory compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Communication/communicationServices +- id: AZ-ACS-003 + severity: required + description: Use user access tokens for client applications — never expose connection strings to clients + rationale: Connection strings grant full access; user tokens are scoped, short-lived, and tied to identity + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Communication/communicationServices +- id: AZ-ACS-004 + severity: recommended + description: Configure custom domains with DKIM and SPF for email sending + rationale: Azure-managed domains have sending limits and cannot be customized; custom domains improve deliverability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Communication/communicationServices +- id: AZ-ACS-005 + severity: recommended + description: Enable diagnostic logging for all communication modalities + rationale: Logs enable troubleshooting, usage analytics, and compliance auditing for chat, SMS, voice, and email + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Communication/communicationServices +patterns: +- name: Communication Services with email and managed identity + description: ACS resource with email service, custom domain, managed identity, and diagnostic logging +anti_patterns: +- description: Do not embed access keys in client applications + instead: Use server-side token issuance with CommunicationIdentityClient to generate scoped user tokens +- description: Do not use Azure-managed domains for production email + instead: Configure customer-managed domains with DKIM, SPF, and DMARC verification +references: +- title: Azure Communication Services documentation + url: https://learn.microsoft.com/azure/communication-services/overview +- title: ACS authentication best practices + url: https://learn.microsoft.com/azure/communication-services/concepts/authentication diff --git a/azext_prototype/governance/policies/azure/management/logic-apps.policy.yaml b/azext_prototype/governance/policies/azure/management/logic-apps.policy.yaml new file mode 100644 index 0000000..846def9 --- /dev/null +++ b/azext_prototype/governance/policies/azure/management/logic-apps.policy.yaml @@ -0,0 +1,206 @@ +kind: policy +domain: azure-management +description: Governance policies for Logic Apps +last_updated: '2026-03-27' +rules: +- id: AZ-LA-001 + severity: required + description: Deploy Logic Apps Standard with managed identity, VNet integration, and disabled public access + rationale: Logic Apps process business workflows that often handle sensitive data; managed identity eliminates connection + credentials + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-logic-app + description: Diagnostic settings to route workflow run logs and trigger events to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_logic_app" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.logic_app_name}" + parent_id = azapi_resource.logic_app.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagLogicApp 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${logicAppName}' + scope: logicApp + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Logic App Contributor + description: RBAC role assignments for Logic App management + targets: + - services: + - Microsoft.Logic/workflows + terraform_pattern: | + resource "azapi_resource" "logic_app" { + type = "Microsoft.Logic/workflows@2019-05-01" + name = var.logic_app_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + state = "Enabled" + accessControl = { + triggers = { + allowedCallerIpAddresses = [] + } + contents = { + allowedCallerIpAddresses = [] + } + actions = { + allowedCallerIpAddresses = [] + } + workflowManagement = { + allowedCallerIpAddresses = [] + } + } + endpointsConfiguration = { + workflow = { + outgoingIpAddresses = [] + accessEndpointIpAddresses = [] + } + connector = { + outgoingIpAddresses = [] + } + } + definition = { + "$schema" = "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#" + contentVersion = "1.0.0.0" + triggers = {} + actions = {} + outputs = {} + } + parameters = {} + } + } + } + bicep_pattern: | + resource logicApp 'Microsoft.Logic/workflows@2019-05-01' = { + name: logicAppName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + state: 'Enabled' + accessControl: { + triggers: { + allowedCallerIpAddresses: [] + } + contents: { + allowedCallerIpAddresses: [] + } + actions: { + allowedCallerIpAddresses: [] + } + workflowManagement: { + allowedCallerIpAddresses: [] + } + } + definition: { + '$schema': 'https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#' + contentVersion: '1.0.0.0' + triggers: {} + actions: {} + outputs: {} + } + parameters: {} + } + } + prohibitions: + - Never hardcode connection strings or credentials in workflow parameters + - Never leave accessControl IP restrictions empty in production — use VNet or specific IPs + - Never embed secrets directly in workflow definitions — use Key Vault references + - Never disable managed identity — it is required for secure API connections + - Never use shared access signature (SAS) trigger URLs without IP restrictions +- id: AZ-LA-002 + severity: required + description: Use managed identity for all API connections instead of connection strings + rationale: Connection strings are shared secrets; managed identity provides per-connection, auditable access + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Logic/workflows +- id: AZ-LA-003 + severity: recommended + description: Configure IP-based access control for triggers, actions, and management endpoints + rationale: IP restrictions limit who can invoke workflows and access run history + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Logic/workflows +- id: AZ-LA-004 + severity: recommended + description: Enable diagnostic logging for workflow runs and trigger history + rationale: Workflow logs provide audit trail and troubleshooting data for business process execution + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Logic/workflows +patterns: +- name: Logic App with managed identity and access control + description: Secure Logic App with managed identity, IP restrictions, and Key Vault-backed parameters +anti_patterns: +- description: Do not hardcode credentials in workflow parameters + instead: Use managed identity for API connections and Key Vault references for secrets +- description: Do not expose trigger URLs without access restrictions + instead: Configure allowedCallerIpAddresses to restrict trigger invocation +references: +- title: Logic Apps security overview + url: https://learn.microsoft.com/azure/logic-apps/logic-apps-securing-a-logic-app +- title: Logic Apps managed identity + url: https://learn.microsoft.com/azure/logic-apps/authenticate-with-managed-identity diff --git a/azext_prototype/governance/policies/azure/management/managed-grafana.policy.yaml b/azext_prototype/governance/policies/azure/management/managed-grafana.policy.yaml new file mode 100644 index 0000000..7607f30 --- /dev/null +++ b/azext_prototype/governance/policies/azure/management/managed-grafana.policy.yaml @@ -0,0 +1,182 @@ +kind: policy +domain: azure-management +description: Governance policies for Managed Grafana +last_updated: '2026-03-27' +rules: +- id: AZ-GRF-001 + severity: required + description: Deploy Azure Managed Grafana with managed identity, deterministic outbound IP, and no public access + rationale: Grafana dashboards access sensitive metrics; managed identity secures data source connections, deterministic + IP enables firewall rules + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-grafana + description: Private endpoint for Managed Grafana to secure dashboard access + terraform_pattern: | + resource "azapi_resource" "pe_grafana" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.grafana_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "grafana-connection" + properties = { + privateLinkServiceId = azapi_resource.grafana.id + groupIds = ["grafana"] + } + } + ] + } + } + } + bicep_pattern: | + resource peGrafana 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${grafanaName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'grafana-connection' + properties: { + privateLinkServiceId: grafana.id + groupIds: ['grafana'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.grafana.azure.com + description: Private DNS zone for Managed Grafana private endpoint resolution + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Grafana Admin / Editor / Viewer + description: RBAC role assignments for Grafana dashboard access — use Viewer for read-only, Editor for dashboard creation + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Monitoring Reader on data sources + description: Grant Grafana managed identity Monitoring Reader on Log Analytics and Azure Monitor workspaces + targets: + - services: + - Microsoft.Dashboard/grafana + terraform_pattern: | + resource "azapi_resource" "grafana" { + type = "Microsoft.Dashboard/grafana@2023-09-01" + name = var.grafana_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + zoneRedundancy = "Enabled" + publicNetworkAccess = "Disabled" + deterministicOutboundIP = "Enabled" + autoGeneratedDomainNameLabelScope = "TenantReuse" + apiKey = "Disabled" + grafanaIntegrations = { + azureMonitorWorkspaceIntegrations = [ + { + azureMonitorWorkspaceResourceId = var.monitor_workspace_id + } + ] + } + } + } + } + bicep_pattern: | + resource grafana 'Microsoft.Dashboard/grafana@2023-09-01' = { + name: grafanaName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + zoneRedundancy: 'Enabled' + publicNetworkAccess: 'Disabled' + deterministicOutboundIP: 'Enabled' + autoGeneratedDomainNameLabelScope: 'TenantReuse' + apiKey: 'Disabled' + grafanaIntegrations: { + azureMonitorWorkspaceIntegrations: [ + { + azureMonitorWorkspaceResourceId: monitorWorkspaceId + } + ] + } + } + } + prohibitions: + - Never enable API key authentication — use Microsoft Entra auth via managed identity + - Never set publicNetworkAccess to Enabled without compensating network controls + - Never grant Grafana Admin to all users — use Viewer/Editor for least privilege + - Never hardcode data source credentials — use managed identity for Azure Monitor data sources + - Never use Essential tier for production — it lacks zone redundancy, private link, and SMTP support +- id: AZ-GRF-002 + severity: required + description: Disable API key authentication — use Microsoft Entra ID only + rationale: API keys bypass Entra ID authentication and cannot be audited per-user + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Dashboard/grafana +- id: AZ-GRF-003 + severity: recommended + description: Enable zone redundancy for high availability + rationale: Zone redundancy ensures dashboard availability during availability zone failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Dashboard/grafana +- id: AZ-GRF-004 + severity: recommended + description: Grant Grafana managed identity Monitoring Reader role on all data sources + rationale: Managed identity access to Azure Monitor eliminates credential management for data source connections + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Dashboard/grafana +patterns: +- name: Managed Grafana with private endpoint and Azure Monitor integration + description: Standard Grafana with private access, managed identity, zone redundancy, and Azure Monitor data sources +anti_patterns: +- description: Do not enable API key authentication + instead: Set apiKey to Disabled and use Microsoft Entra ID authentication +- description: Do not configure data sources with stored credentials + instead: Use managed identity with Monitoring Reader role for Azure Monitor data sources +references: +- title: Azure Managed Grafana documentation + url: https://learn.microsoft.com/azure/managed-grafana/overview +- title: Managed Grafana authentication + url: https://learn.microsoft.com/azure/managed-grafana/how-to-authentication-permissions diff --git a/azext_prototype/governance/policies/azure/messaging/__init__.py b/azext_prototype/governance/policies/azure/messaging/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/messaging/notification-hubs.policy.yaml b/azext_prototype/governance/policies/azure/messaging/notification-hubs.policy.yaml new file mode 100644 index 0000000..3b0f546 --- /dev/null +++ b/azext_prototype/governance/policies/azure/messaging/notification-hubs.policy.yaml @@ -0,0 +1,195 @@ +kind: policy +domain: azure-messaging +description: Governance policies for Notification Hubs +last_updated: '2026-03-27' +rules: +- id: AZ-NH-001 + severity: required + description: Deploy Notification Hubs namespace with Standard SKU, managed identity, and no public access + rationale: Standard SKU provides SLA, telemetry, and scheduled push; managed identity eliminates SAS key management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview + name: notification-hub + description: Notification Hub within the namespace for platform notification service (PNS) integration + terraform_pattern: | + resource "azapi_resource" "notification_hub" { + type = "Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview" + name = var.hub_name + parent_id = azapi_resource.nh_namespace.id + location = var.location + + body = { + properties = { + name = var.hub_name + } + } + } + bicep_pattern: | + resource notificationHub 'Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview' = { + name: hubName + parent: nhNamespace + location: location + properties: { + name: hubName + } + } + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-nh + description: Private endpoint for Notification Hubs namespace + terraform_pattern: | + resource "azapi_resource" "pe_nh" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.nh_namespace_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "nh-connection" + properties = { + privateLinkServiceId = azapi_resource.nh_namespace.id + groupIds = ["namespace"] + } + } + ] + } + } + } + bicep_pattern: | + resource peNh 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${nhNamespaceName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'nh-connection' + properties: { + privateLinkServiceId: nhNamespace.id + groupIds: ['namespace'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.servicebus.windows.net + description: Private DNS zone for Notification Hubs private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-nh + description: Diagnostic settings for push notification delivery logs + targets: + - services: + - Microsoft.NotificationHubs/namespaces + terraform_pattern: | + resource "azapi_resource" "nh_namespace" { + type = "Microsoft.NotificationHubs/namespaces@2023-10-01-preview" + name = var.nh_namespace_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + tier = "Standard" + } + properties = { + zoneRedundancy = "Enabled" + publicNetworkAccess = "Disabled" + replicationRegion = var.replication_region + networkAcls = { + ipRules = [] + publicNetworkRule = { + rights = [] + } + } + } + } + } + bicep_pattern: | + resource nhNamespace 'Microsoft.NotificationHubs/namespaces@2023-10-01-preview' = { + name: nhNamespaceName + location: location + sku: { + name: 'Standard' + tier: 'Standard' + } + properties: { + zoneRedundancy: 'Enabled' + publicNetworkAccess: 'Disabled' + replicationRegion: replicationRegion + networkAcls: { + ipRules: [] + publicNetworkRule: { + rights: [] + } + } + } + } + prohibitions: + - Never hardcode PNS (APNS, FCM, WNS) credentials in IaC — use Key Vault references + - Never use Free tier for production — it lacks SLA, telemetry, and scheduled push + - Never distribute full access SAS keys to client applications — use registration-scoped keys + - Never set publicNetworkAccess to Enabled without IP rules + - Never embed SAS connection strings in mobile application packages +- id: AZ-NH-002 + severity: required + description: Store PNS credentials (APNS certificates, FCM keys) in Key Vault and reference from hub configuration + rationale: PNS credentials are sensitive and must be rotated; Key Vault provides audited access and rotation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.NotificationHubs/namespaces +- id: AZ-NH-003 + severity: recommended + description: Use installation-based registration for device management + rationale: Installations provide a newer API, support multiple PNS handles per device, and enable partial updates + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.NotificationHubs/namespaces +- id: AZ-NH-004 + severity: recommended + description: Enable zone redundancy for high availability + rationale: Zone redundancy ensures notification delivery during availability zone failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.NotificationHubs/namespaces +patterns: +- name: Notification Hubs with private endpoint and zone redundancy + description: Standard tier namespace with zone redundancy, private endpoints, and Key Vault-backed PNS credentials +anti_patterns: +- description: Do not embed PNS credentials in IaC templates + instead: Store APNS certificates, FCM keys, and WNS secrets in Key Vault +- description: Do not distribute full access SAS keys to clients + instead: Use listen-only or registration-scoped SAS policies for client applications +references: +- title: Azure Notification Hubs documentation + url: https://learn.microsoft.com/azure/notification-hubs/notification-hubs-push-notification-overview +- title: Notification Hubs security + url: https://learn.microsoft.com/azure/notification-hubs/notification-hubs-push-notification-security diff --git a/azext_prototype/governance/policies/azure/messaging/signalr.policy.yaml b/azext_prototype/governance/policies/azure/messaging/signalr.policy.yaml new file mode 100644 index 0000000..31aa738 --- /dev/null +++ b/azext_prototype/governance/policies/azure/messaging/signalr.policy.yaml @@ -0,0 +1,263 @@ +kind: policy +domain: azure-messaging +description: Governance policies for Signalr +last_updated: '2026-03-27' +rules: +- id: AZ-SIG-001 + severity: required + description: Deploy Azure SignalR Service with managed identity, disabled access keys, and no public access + rationale: Access keys are shared secrets; managed identity with Microsoft Entra auth provides auditable, per-client access + control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-signalr + description: Private endpoint for SignalR Service to secure real-time connections + terraform_pattern: | + resource "azapi_resource" "pe_signalr" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.signalr_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "signalr-connection" + properties = { + privateLinkServiceId = azapi_resource.signalr.id + groupIds = ["signalr"] + } + } + ] + } + } + } + bicep_pattern: | + resource peSignalr 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${signalrName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'signalr-connection' + properties: { + privateLinkServiceId: signalr.id + groupIds: ['signalr'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.service.signalr.net + description: Private DNS zone for SignalR Service private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-signalr + description: Diagnostic settings for connectivity and messaging logs to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_signalr" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.signalr_name}" + parent_id = azapi_resource.signalr.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagSignalr 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${signalrName}' + scope: signalr + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: SignalR App Server + description: 'RBAC role assignment granting the app server identity the SignalR App Server role (roleDefinitionId: 420fcaa2-552c-430f-98ca-3264be4806c7)' + targets: + - services: + - Microsoft.SignalRService/signalR + terraform_pattern: | + resource "azapi_resource" "signalr" { + type = "Microsoft.SignalRService/signalR@2024-03-01" + name = var.signalr_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + kind = "SignalR" + sku = { + name = var.sku_name # "Standard_S1", "Premium_P1" + tier = var.sku_tier # "Standard", "Premium" + capacity = var.sku_capacity + } + properties = { + disableLocalAuth = true + publicNetworkAccess = "Disabled" + tls = { + clientCertEnabled = false + } + features = [ + { + flag = "ServiceMode" + value = "Default" + }, + { + flag = "EnableConnectivityLogs" + value = "True" + }, + { + flag = "EnableMessagingLogs" + value = "True" + }, + { + flag = "EnableLiveTrace" + value = "False" + } + ] + networkACLs = { + defaultAction = "Deny" + publicNetwork = { + allow = [] + deny = ["ServerConnection", "ClientConnection", "RESTAPI", "Trace"] + } + privateEndpoints = [] + } + } + } + } + bicep_pattern: | + resource signalr 'Microsoft.SignalRService/signalR@2024-03-01' = { + name: signalrName + location: location + kind: 'SignalR' + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + tier: skuTier + capacity: skuCapacity + } + properties: { + disableLocalAuth: true + publicNetworkAccess: 'Disabled' + tls: { + clientCertEnabled: false + } + features: [ + { + flag: 'ServiceMode' + value: 'Default' + } + { + flag: 'EnableConnectivityLogs' + value: 'True' + } + { + flag: 'EnableMessagingLogs' + value: 'True' + } + { + flag: 'EnableLiveTrace' + value: 'False' + } + ] + networkACLs: { + defaultAction: 'Deny' + publicNetwork: { + allow: [] + deny: ['ServerConnection', 'ClientConnection', 'RESTAPI', 'Trace'] + } + privateEndpoints: [] + } + } + } + prohibitions: + - Never hardcode SignalR access keys or connection strings in application code + - Never set disableLocalAuth to false — always use Microsoft Entra authentication + - Never set publicNetworkAccess to Enabled without network ACLs + - Never enable LiveTrace in production — it is for debugging only + - Never use Free tier for production — it lacks SLA and private endpoint support + - When disableLocalAuth = true, primaryConnectionString and primaryKey are null in the ARM response. NEVER output or reference + them. + - Applications authenticate to SignalR via managed identity using DefaultAzureCredential, NOT connection strings. +- id: AZ-SIG-002 + severity: required + description: Enable connectivity and messaging logs for connection tracking and troubleshooting + rationale: Without logs, connection failures and message delivery issues cannot be diagnosed + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.SignalRService/signalR +- id: AZ-SIG-003 + severity: recommended + description: Configure network ACLs to restrict access by connection type + rationale: Network ACLs provide fine-grained control over which connection types are allowed through which endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.SignalRService/signalR +patterns: +- name: SignalR with private endpoint and Microsoft Entra auth + description: Secure SignalR deployment with no public access, managed identity, and connectivity logging +anti_patterns: +- description: Do not use access key authentication for SignalR + instead: Set disableLocalAuth=true and use managed identity with SignalR App Server role +- description: Do not deploy SignalR with public network access + instead: Set publicNetworkAccess to Disabled and use private endpoints +references: +- title: Azure SignalR Service documentation + url: https://learn.microsoft.com/azure/azure-signalr/signalr-overview +- title: SignalR Service authentication + url: https://learn.microsoft.com/azure/azure-signalr/signalr-concept-authenticate-oauth diff --git a/azext_prototype/governance/policies/azure/monitoring.policy.yaml b/azext_prototype/governance/policies/azure/monitoring.policy.yaml deleted file mode 100644 index da8185d..0000000 --- a/azext_prototype/governance/policies/azure/monitoring.policy.yaml +++ /dev/null @@ -1,80 +0,0 @@ -apiVersion: v1 -kind: policy -metadata: - name: monitoring - category: azure - services: [app-service, functions, container-apps, key-vault, sql-database, cosmos-db, storage, api-management] - last_reviewed: "2026-02-01" - -rules: - - id: MON-001 - severity: recommended - description: "Deploy a Log Analytics workspace and route all diagnostic logs to it" - rationale: "Centralized logging is required for incident investigation and compliance" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent, biz-analyst] - template_check: - require_service: [log-analytics] - error_message: "Template missing a log-analytics service for centralized logging" - - - id: MON-002 - severity: recommended - description: "Enable Application Insights for all web apps, APIs, and functions" - rationale: "Distributed tracing, performance monitoring, and failure detection" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent, app-developer] - template_check: - when_services_present: [app-service, functions, container-apps] - require_service: [application-insights] - error_message: "Template with compute services should include application-insights" - - - id: MON-003 - severity: required - description: "Enable diagnostic settings on all PaaS resources" - rationale: "Without diagnostic settings, resource-level logs are not captured" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent] - - - id: MON-004 - severity: recommended - description: "Configure alerts for critical metrics (response time, error rate, CPU, memory)" - rationale: "Proactive detection of issues before they impact users" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent] - - - id: MON-005 - severity: recommended - description: "Set up action groups for alert notification routing" - rationale: "Ensures the right team is notified when issues occur" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent] - - - id: MON-006 - severity: recommended - description: "Enable Container Apps system logs and console logs" - rationale: "Container Apps require explicit log configuration for stdout/stderr capture" - applies_to: [cloud-architect, terraform-agent, bicep-agent, monitoring-agent] - -patterns: - - name: "Log Analytics with diagnostic settings" - description: "Central Log Analytics workspace with diagnostic settings for all resources" - example: | - resource "azurerm_log_analytics_workspace" "main" { - name = "log-${var.project}" - sku = "PerGB2018" - retention_in_days = 30 - } - resource "azurerm_monitor_diagnostic_setting" "kv" { - name = "diag-kv" - target_resource_id = azurerm_key_vault.main.id - log_analytics_workspace_id = azurerm_log_analytics_workspace.main.id - enabled_log { category = "AuditEvent" } - metric { category = "AllMetrics" } - } - -anti_patterns: - - description: "Do not deploy resources without diagnostic settings" - instead: "Configure azurerm_monitor_diagnostic_setting for every PaaS resource" - - description: "Do not rely solely on portal metrics — capture logs for post-incident analysis" - instead: "Route logs to Log Analytics for queryable, long-term storage" - -references: - - title: "Azure Monitor overview" - url: "https://learn.microsoft.com/azure/azure-monitor/overview" - - title: "Diagnostic settings in Azure Monitor" - url: "https://learn.microsoft.com/azure/azure-monitor/essentials/diagnostic-settings" diff --git a/azext_prototype/governance/policies/azure/monitoring/__init__.py b/azext_prototype/governance/policies/azure/monitoring/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/monitoring/action-groups.policy.yaml b/azext_prototype/governance/policies/azure/monitoring/action-groups.policy.yaml new file mode 100644 index 0000000..a34ef3d --- /dev/null +++ b/azext_prototype/governance/policies/azure/monitoring/action-groups.policy.yaml @@ -0,0 +1,305 @@ +kind: policy +domain: azure-monitoring +description: Governance policies for Action Groups +last_updated: '2026-03-27' +rules: +- id: AZ-AG-001 + severity: required + description: Create action groups with email and webhook notification channels for critical alerts + rationale: Without action groups, alerts fire but nobody is notified — incidents go undetected + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/metricAlerts@2018-03-01 + name: alert-critical-metrics + description: Metric alert rules that reference this action group for notification delivery + - type: Microsoft.Insights/scheduledQueryRules@2023-03-15-preview + name: alert-log-query + description: Log alert rules based on KQL queries that reference this action group + - type: Microsoft.Insights/activityLogAlerts@2020-10-01 + name: alert-activity-log + description: Activity log alerts for subscription-level administrative events + targets: + - services: + - Microsoft.Insights/actionGroups + terraform_pattern: | + resource "azapi_resource" "action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = var.action_group_name + location = "global" + parent_id = var.resource_group_id + body = { + properties = { + groupShortName = var.short_name + enabled = true + emailReceivers = [ + { + name = "ops-team" + emailAddress = var.ops_email + useCommonAlertSchema = true + } + ] + azureAppPushReceivers = [] + smsReceivers = [] + webhookReceivers = [ + { + name = "teams-webhook" + serviceUri = var.teams_webhook_uri + useCommonAlertSchema = true + useAadAuth = false + } + ] + armRoleReceivers = [ + { + name = "monitoring-contributor" + roleId = "749f88d5-cbae-40b8-bcfc-e573ddc772fa" + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + resource actionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: actionGroupName + location: 'global' + properties: { + groupShortName: shortName + enabled: true + emailReceivers: [ + { + name: 'ops-team' + emailAddress: opsEmail + useCommonAlertSchema: true + } + ] + azureAppPushReceivers: [] + smsReceivers: [] + webhookReceivers: [ + { + name: 'teams-webhook' + serviceUri: teamsWebhookUri + useCommonAlertSchema: true + useAadAuth: false + } + ] + armRoleReceivers: [ + { + name: 'monitoring-contributor' + roleId: '749f88d5-cbae-40b8-bcfc-e573ddc772fa' + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - Do not create action groups without at least one notification receiver + - Do not hardcode webhook URIs in templates — use Key Vault references or parameters + - Do not use personal email addresses — use distribution lists or shared mailboxes + - Do not disable action groups without documenting the reason +- id: AZ-AG-002 + severity: required + description: Use Common Alert Schema for all receivers + rationale: Common Alert Schema provides a standardized payload format across all alert types for consistent processing + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: [] + targets: + - services: + - Microsoft.Insights/actionGroups + terraform_pattern: | + # Set useCommonAlertSchema = true on all receivers + # See AG-001 terraform_pattern for full example + bicep_pattern: | + // Set useCommonAlertSchema: true on all receivers + // See AG-001 bicep_pattern for full example + prohibitions: + - Do not set useCommonAlertSchema to false — non-standard payloads require custom parsing per alert type +- id: AZ-AG-003 + severity: required + description: Create metric alerts for critical resource health indicators + rationale: Proactive alerting on CPU, memory, response time, and error rate prevents outages from going undetected + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ag-ops + description: Action group defining notification receivers for metric alert delivery + targets: + - services: + - Microsoft.Insights/actionGroups + terraform_pattern: | + resource "azapi_resource" "metric_alert" { + type = "Microsoft.Insights/metricAlerts@2018-03-01" + name = var.alert_name + location = "global" + parent_id = var.resource_group_id + body = { + properties = { + description = var.alert_description + severity = 2 + enabled = true + scopes = [var.target_resource_id] + evaluationFrequency = "PT5M" + windowSize = "PT15M" + criteria = { + "odata.type" = "Microsoft.Azure.Monitor.SingleResourceMultipleMetricCriteria" + allOf = [ + { + criterionType = "StaticThresholdCriterion" + name = "cpu-threshold" + metricName = "Percentage CPU" + metricNamespace = "Microsoft.Compute/virtualMachines" + operator = "GreaterThan" + threshold = 90 + timeAggregation = "Average" + } + ] + } + actions = [ + { + actionGroupId = azapi_resource.action_group.id + } + ] + } + } + } + bicep_pattern: | + resource metricAlert 'Microsoft.Insights/metricAlerts@2018-03-01' = { + name: alertName + location: 'global' + properties: { + description: alertDescription + severity: 2 + enabled: true + scopes: [targetResourceId] + evaluationFrequency: 'PT5M' + windowSize: 'PT15M' + criteria: { + 'odata.type': 'Microsoft.Azure.Monitor.SingleResourceMultipleMetricCriteria' + allOf: [ + { + criterionType: 'StaticThresholdCriterion' + name: 'cpu-threshold' + metricName: 'Percentage CPU' + metricNamespace: 'Microsoft.Compute/virtualMachines' + operator: 'GreaterThan' + threshold: 90 + timeAggregation: 'Average' + } + ] + } + actions: [ + { + actionGroupId: actionGroup.id + } + ] + } + } + prohibitions: + - Do not create alerts without action groups — unnotified alerts are useless + - Do not set severity to 4 (Verbose) for critical metrics — use 0 (Critical) or 1 (Error) +- id: AZ-AG-004 + severity: recommended + description: Create activity log alerts for subscription-level administrative events + rationale: Track resource deletions, role assignments, and policy changes at the subscription level + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ag-ops + description: Action group defining notification receivers for activity log alert delivery + targets: + - services: + - Microsoft.Insights/actionGroups + terraform_pattern: | + resource "azapi_resource" "activity_log_alert" { + type = "Microsoft.Insights/activityLogAlerts@2020-10-01" + name = var.activity_alert_name + location = "global" + parent_id = var.resource_group_id + body = { + properties = { + description = "Alert on resource deletions" + enabled = true + scopes = ["/subscriptions/${var.subscription_id}"] + condition = { + allOf = [ + { + field = "category" + equals = "Administrative" + }, + { + field = "operationName" + equals = "Microsoft.Resources/subscriptions/resourceGroups/delete" + } + ] + } + actions = { + actionGroups = [ + { + actionGroupId = azapi_resource.action_group.id + } + ] + } + } + } + } + bicep_pattern: | + resource activityLogAlert 'Microsoft.Insights/activityLogAlerts@2020-10-01' = { + name: activityAlertName + location: 'global' + properties: { + description: 'Alert on resource deletions' + enabled: true + scopes: ['/subscriptions/${subscriptionId}'] + condition: { + allOf: [ + { + field: 'category' + equals: 'Administrative' + } + { + field: 'operationName' + equals: 'Microsoft.Resources/subscriptions/resourceGroups/delete' + } + ] + } + actions: { + actionGroups: [ + { + actionGroupId: actionGroup.id + } + ] + } + } + } + prohibitions: + - Do not alert on all activity log events — filter to specific critical operations +patterns: +- name: Action group with multi-channel notifications and metric alerts + description: Action group with email, webhook, and role-based receivers linked to metric alerts + example: | + # See AG-001 through AG-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy monitoring without action groups + instead: Create action groups first, then link them to all alert rules +- description: Do not use personal email addresses in action groups + instead: Use distribution lists or team mailboxes for reliable notification delivery +references: +- title: Action groups documentation + url: https://learn.microsoft.com/azure/azure-monitor/alerts/action-groups +- title: Common Alert Schema + url: https://learn.microsoft.com/azure/azure-monitor/alerts/alerts-common-schema diff --git a/azext_prototype/governance/policies/azure/monitoring/app-insights.policy.yaml b/azext_prototype/governance/policies/azure/monitoring/app-insights.policy.yaml new file mode 100644 index 0000000..fbd6bb9 --- /dev/null +++ b/azext_prototype/governance/policies/azure/monitoring/app-insights.policy.yaml @@ -0,0 +1,127 @@ +kind: policy +domain: azure-monitoring +description: Governance policies for App Insights +last_updated: '2026-03-27' +rules: +- id: AZ-AI-001 + severity: required + description: Create Application Insights linked to Log Analytics Workspace with workspace-based mode + rationale: Workspace-based Application Insights is the current model; classic mode is deprecated. WorkspaceResourceId links + telemetry to Log Analytics for unified querying + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Insights/components + terraform_pattern: | + resource "azapi_resource" "app_insights" { + type = "Microsoft.Insights/components@2020-02-02" + name = var.app_insights_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "web" + properties = { + Application_Type = "web" + WorkspaceResourceId = azapi_resource.log_analytics_workspace.id + SamplingPercentage = 100 + } + } + } + + output "app_insights_connection_string" { + value = azapi_resource.app_insights.output.properties.ConnectionString + sensitive = true + } + + output "app_insights_instrumentation_key" { + value = azapi_resource.app_insights.output.properties.InstrumentationKey + sensitive = true + } + bicep_pattern: | + resource appInsights 'Microsoft.Insights/components@2020-02-02' = { + name: appInsightsName + location: location + kind: 'web' + properties: { + Application_Type: 'web' + WorkspaceResourceId: logAnalyticsWorkspace.id + SamplingPercentage: 100 + } + } + + output appInsightsConnectionString string = appInsights.properties.ConnectionString + output appInsightsInstrumentationKey string = appInsights.properties.InstrumentationKey + prohibitions: + - NEVER use API version 2024-03-01 — it does not exist for Microsoft.Insights/components + - NEVER create classic (non-workspace-based) Application Insights — always set WorkspaceResourceId + - NEVER include publicNetworkAccessForIngestion or publicNetworkAccessForQuery on Microsoft.Insights/components@2020-02-02 + — these properties are NOT supported on this API version + - NEVER use InstrumentationKey for new integrations — use ConnectionString instead + - NEVER set RetentionInDays on workspace-based Application Insights — this property does not exist on + Microsoft.Insights/components@2020-02-02; retention is controlled by the linked Log Analytics workspace +- id: AZ-AI-002 + severity: required + description: Link Application Insights to Log Analytics Workspace via WorkspaceResourceId + rationale: Without WorkspaceResourceId, Application Insights creates in classic mode which is deprecated and lacks unified + query support + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + when_services_present: + - app-service + - functions + - container-apps + require_service: + - application-insights + error_message: Template with compute services should include application-insights for observability + targets: + - services: + - Microsoft.Insights/components +- id: AZ-AI-003 + severity: recommended + description: Set SamplingPercentage to 100 for POC, reduce for high-traffic production + rationale: Full sampling captures all telemetry for debugging; reduce to 10-50% for high-volume production to control costs + applies_to: + - cloud-architect + - monitoring-agent + - cost-analyst + targets: + - services: + - Microsoft.Insights/components +- id: AZ-AI-004 + severity: recommended + description: Output ConnectionString for downstream app configuration + rationale: Compute resources need the connection string to send telemetry; prefer ConnectionString over InstrumentationKey + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Insights/components +patterns: +- name: Application Insights linked to Log Analytics + description: Workspace-based Application Insights with connection string output for app configuration +anti_patterns: +- description: Do not create classic Application Insights without WorkspaceResourceId + instead: Always set WorkspaceResourceId to link to Log Analytics Workspace +- description: Do not use API version 2024-03-01 for Microsoft.Insights/components + instead: Use API version 2020-02-02 which is the current stable version +- description: Do not include publicNetworkAccess properties on Application Insights 2020-02-02 + instead: Control network access via the linked Log Analytics Workspace and Azure Monitor Private Link Scope +- description: Do not use InstrumentationKey for new integrations + instead: Use ConnectionString which includes the ingestion endpoint and is forward-compatible +references: +- title: Application Insights overview + url: https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview +- title: Workspace-based Application Insights + url: https://learn.microsoft.com/azure/azure-monitor/app/create-workspace-resource +- title: Application Insights sampling + url: https://learn.microsoft.com/azure/azure-monitor/app/sampling-classic-api diff --git a/azext_prototype/governance/policies/azure/monitoring/log-analytics.policy.yaml b/azext_prototype/governance/policies/azure/monitoring/log-analytics.policy.yaml new file mode 100644 index 0000000..4a1b271 --- /dev/null +++ b/azext_prototype/governance/policies/azure/monitoring/log-analytics.policy.yaml @@ -0,0 +1,253 @@ +kind: policy +domain: azure-monitoring +description: Governance policies for Log Analytics +last_updated: '2026-03-27' +rules: +- id: AZ-LA-001 + severity: required + description: Create Log Analytics Workspace with PerGB2018 SKU and appropriate retention + rationale: PerGB2018 is the standard pricing tier; retention controls cost and compliance requirements + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-log-analytics + description: Private endpoint for Log Analytics ingestion — required when publicNetworkAccessForIngestion is Disabled + terraform_pattern: | + resource "azapi_resource" "la_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.log_analytics_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.log_analytics_name}" + properties = { + privateLinkServiceId = azapi_resource.log_analytics_workspace.id + groupIds = ["azuremonitor"] + } + } + ] + } + } + } + bicep_pattern: | + resource laPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${logAnalyticsName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${logAnalyticsName}' + properties: { + privateLinkServiceId: logAnalyticsWorkspace.id + groupIds: [ + 'azuremonitor' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.oms.opinsights.azure.com + description: Private DNS zones for Log Analytics private endpoint resolution (requires multiple zones) + terraform_pattern: | + locals { + monitor_dns_zones = [ + "privatelink.oms.opinsights.azure.com", + "privatelink.ods.opinsights.azure.com", + "privatelink.agentsvc.azure-automation.net", + "privatelink.monitor.azure.com" + ] + } + + resource "azapi_resource" "la_dns_zones" { + for_each = toset(local.monitor_dns_zones) + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = each.value + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "la_dns_zone_links" { + for_each = toset(local.monitor_dns_zones) + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.la_dns_zones[each.key].id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "la_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.la_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + for zone in local.monitor_dns_zones : { + name = replace(zone, ".", "-") + properties = { + privateDnsZoneId = azapi_resource.la_dns_zones[zone].id + } + } + ] + } + } + } + bicep_pattern: | + var monitorDnsZones = [ + 'privatelink.oms.opinsights.azure.com' + 'privatelink.ods.opinsights.azure.com' + 'privatelink.agentsvc.azure-automation.net' + 'privatelink.monitor.azure.com' + ] + + resource laDnsZones 'Microsoft.Network/privateDnsZones@2020-06-01' = [for zone in monitorDnsZones: { + name: zone + location: 'global' + }] + + resource laDnsZoneLinks 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = [for (zone, i) in monitorDnsZones: { + parent: laDnsZones[i] + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + }] + + resource laPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: laPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [for (zone, i) in monitorDnsZones: { + name: replace(zone, '.', '-') + properties: { + privateDnsZoneId: laDnsZones[i].id + } + }] + } + } + targets: + - services: + - Microsoft.OperationalInsights/workspaces + terraform_pattern: | + resource "azapi_resource" "log_analytics_workspace" { + type = "Microsoft.OperationalInsights/workspaces@2023-09-01" + name = var.log_analytics_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + sku = { + name = "PerGB2018" + } + retentionInDays = 30 + disableLocalAuth = false + publicNetworkAccessForIngestion = "Disabled" + publicNetworkAccessForQuery = "Disabled" + features = { + enableLogAccessUsingOnlyResourcePermissions = true + } + # CRITICAL: disableLocalAuth MUST be a direct child of properties, + # NEVER inside features. ARM silently drops it if nested wrong. + } + } + } + + output "log_analytics_workspace_id" { + value = azapi_resource.log_analytics_workspace.id + } + + output "log_analytics_customer_id" { + value = azapi_resource.log_analytics_workspace.output.properties.customerId + } + bicep_pattern: | + resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' = { + name: logAnalyticsName + location: location + properties: { + sku: { + name: 'PerGB2018' + } + retentionInDays: 30 + publicNetworkAccessForIngestion: 'Disabled' + publicNetworkAccessForQuery: 'Disabled' + features: { + enableLogAccessUsingOnlyResourcePermissions: true + } + } + } + + output logAnalyticsWorkspaceId string = logAnalyticsWorkspace.id + output logAnalyticsCustomerId string = logAnalyticsWorkspace.properties.customerId + prohibitions: + - NEVER place disableLocalAuth inside properties.features — it MUST be a direct child of properties. + ARM silently drops it if nested inside features, leaving local auth enabled. + - NEVER use Free SKU for production or shared workspaces — use PerGB2018 + - NEVER set retentionInDays below 30 for compliance-sensitive workloads + - NEVER set publicNetworkAccessForIngestion to Enabled when private endpoints are available + - NEVER set publicNetworkAccessForQuery to Enabled when private endpoints are available +- id: AZ-LA-002 + severity: required + description: Output workspace ID and customer ID for downstream diagnostic settings + rationale: All PaaS resources need the workspace ID for diagnostic settings; Container Apps need the customer ID + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.OperationalInsights/workspaces +- id: AZ-LA-003 + severity: recommended + description: Set retention to 30 days for POC, 90 days for production + rationale: Longer retention increases cost; 30 days is sufficient for POC troubleshooting + applies_to: + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.OperationalInsights/workspaces +patterns: +- name: Log Analytics Workspace with private endpoint + description: Complete Log Analytics deployment with PerGB2018 SKU, private access, and DNS configuration +anti_patterns: +- description: Do not deploy resources without routing diagnostics to Log Analytics + instead: Create diagnostic settings on every PaaS resource pointing to the shared workspace +- description: Do not use Free SKU for shared workspaces + instead: Use PerGB2018 for predictable pricing and full feature set +references: +- title: Log Analytics workspace overview + url: https://learn.microsoft.com/azure/azure-monitor/logs/log-analytics-workspace-overview +- title: Azure Monitor private link + url: https://learn.microsoft.com/azure/azure-monitor/logs/private-link-security +- title: Log Analytics pricing + url: https://learn.microsoft.com/azure/azure-monitor/logs/cost-logs diff --git a/azext_prototype/governance/policies/azure/networking/__init__.py b/azext_prototype/governance/policies/azure/networking/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/networking/application-gateway.policy.yaml b/azext_prototype/governance/policies/azure/networking/application-gateway.policy.yaml new file mode 100644 index 0000000..6d27ee8 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/application-gateway.policy.yaml @@ -0,0 +1,479 @@ +kind: policy +domain: azure-networking +description: Governance policies for Application Gateway +last_updated: '2026-03-27' +rules: +- id: AZ-AGW-001 + severity: required + description: Deploy Application Gateway v2 with WAF_v2 SKU for web application protection + rationale: v2 SKU provides autoscaling, zone redundancy, and WAF v2 includes OWASP CRS and bot protection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-agw + description: Standard SKU static public IP for Application Gateway frontend listener + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-agw + description: Dedicated subnet for Application Gateway (/24 recommended) + - type: Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies@2024-01-01 + name: waf-policy + description: WAF policy with OWASP CRS rules for Application Gateway protection + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-agw + description: Diagnostic settings routing access logs and WAF logs to Log Analytics + - type: Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31 + name: id-agw + description: User-assigned identity for Application Gateway Key Vault SSL certificate access + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2024-01-01" + name = var.agw_name + location = var.location + parent_id = var.resource_group_id + body = { + zones = ["1", "2", "3"] + properties = { + sku = { + name = "WAF_v2" + tier = "WAF_v2" + } + autoscaleConfiguration = { + minCapacity = 1 + maxCapacity = 10 + } + gatewayIPConfigurations = [ + { + name = "appGatewayIpConfig" + properties = { + subnet = { + id = var.agw_subnet_id + } + } + } + ] + frontendIPConfigurations = [ + { + name = "appGatewayFrontendIp" + properties = { + publicIPAddress = { + id = azapi_resource.agw_pip.id + } + } + } + ] + frontendPorts = [ + { + name = "port_443" + properties = { + port = 443 + } + } + ] + sslPolicy = { + policyType = "Predefined" + policyName = "AppGwSslPolicy20220101S" + } + enableHttp2 = true + } + } + } + bicep_pattern: | + resource appGateway 'Microsoft.Network/applicationGateways@2024-01-01' = { + name: agwName + location: location + zones: ['1', '2', '3'] + properties: { + sku: { + name: 'WAF_v2' + tier: 'WAF_v2' + } + autoscaleConfiguration: { + minCapacity: 1 + maxCapacity: 10 + } + gatewayIPConfigurations: [ + { + name: 'appGatewayIpConfig' + properties: { + subnet: { + id: agwSubnetId + } + } + } + ] + frontendIPConfigurations: [ + { + name: 'appGatewayFrontendIp' + properties: { + publicIPAddress: { + id: agwPip.id + } + } + } + ] + frontendPorts: [ + { + name: 'port_443' + properties: { + port: 443 + } + } + ] + sslPolicy: { + policyType: 'Predefined' + policyName: 'AppGwSslPolicy20220101S' + } + enableHttp2: true + } + } + prohibitions: + - Do not use v1 SKU — it lacks autoscaling, zone redundancy, and advanced WAF + - Do not use Standard_v2 without WAF unless WAF is handled upstream by a CDN/Front Door + - Do not deploy without zone redundancy in production +- id: AZ-AGW-002 + severity: required + description: Configure WAF policy in Prevention mode with OWASP 3.2 ruleset + rationale: Detection mode only logs; Prevention mode blocks attacks. OWASP 3.2 is the latest stable ruleset + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.Network/applicationGateways@2024-01-01 + name: agw + description: Application Gateway to associate the WAF policy with + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + resource "azapi_resource" "waf_policy" { + type = "Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies@2024-01-01" + name = var.waf_policy_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + policySettings = { + state = "Enabled" + mode = "Prevention" + requestBodyCheck = true + maxRequestBodySizeInKb = 128 + fileUploadLimitInMb = 100 + } + managedRules = { + managedRuleSets = [ + { + ruleSetType = "OWASP" + ruleSetVersion = "3.2" + } + ] + } + } + } + } + bicep_pattern: | + resource wafPolicy 'Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies@2024-01-01' = { + name: wafPolicyName + location: location + properties: { + policySettings: { + state: 'Enabled' + mode: 'Prevention' + requestBodyCheck: true + maxRequestBodySizeInKb: 128 + fileUploadLimitInMb: 100 + } + managedRules: { + managedRuleSets: [ + { + ruleSetType: 'OWASP' + ruleSetVersion: '3.2' + } + ] + } + } + } + prohibitions: + - Do not use Detection mode in production — it only logs and does not block attacks + - Do not disable requestBodyCheck — it leaves the application vulnerable to body-based attacks + - Do not use OWASP 2.x rulesets — they are outdated +- id: AZ-AGW-003 + severity: required + description: Enforce TLS 1.2+ with strong SSL policy for all HTTPS listeners + rationale: Older TLS versions and weak cipher suites are vulnerable to downgrade attacks + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: kv-certs + description: Key Vault storing SSL/TLS certificates for Application Gateway HTTPS listeners + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # Configure sslPolicy in the Application Gateway resource + # See AGW-001 terraform_pattern — sslPolicy section + # Use AppGwSslPolicy20220101S or custom policy with TLS 1.2+ only + bicep_pattern: | + // Configure sslPolicy in the Application Gateway resource + // See AGW-001 bicep_pattern — sslPolicy section + // Use AppGwSslPolicy20220101S or custom policy with TLS 1.2+ only + prohibitions: + - Do not use AppGwSslPolicy20150501 or older policies — they allow TLS 1.0/1.1 + - Do not use self-signed certificates in production + - Do not hardcode SSL certificate passwords in templates +- id: AZ-AGW-004 + severity: recommended + description: Enable diagnostic settings for access logs, performance logs, and WAF logs + rationale: Access logs are essential for troubleshooting; WAF logs track blocked requests + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Application Gateway diagnostic logs + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + resource "azapi_resource" "agw_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-app-gateway" + parent_id = azapi_resource.app_gateway.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "ApplicationGatewayAccessLog" + enabled = true + }, + { + category = "ApplicationGatewayPerformanceLog" + enabled = true + }, + { + category = "ApplicationGatewayFirewallLog" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource agwDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-app-gateway' + scope: appGateway + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'ApplicationGatewayAccessLog' + enabled: true + } + { + category: 'ApplicationGatewayPerformanceLog' + enabled: true + } + { + category: 'ApplicationGatewayFirewallLog' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit ApplicationGatewayFirewallLog when WAF is enabled +- id: AZ-AGW-005 + severity: recommended + description: Configure autoscaling with appropriate minimum and maximum instance counts + rationale: 'WAF Performance/Reliability: Autoscaling takes 3-5 minutes to provision new instances; setting a minimum based + on average compute units prevents transient latency during traffic spikes' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # In AGW-001, the autoscaleConfiguration is already present. + # WAF guidance: set minCapacity based on peak compute units / 10 + # Set maxCapacity to 125 (maximum possible) to handle surge traffic + # autoscaleConfiguration = { + # minCapacity = var.agw_min_capacity # e.g. 2-3 based on baseline + # maxCapacity = 125 + # } + bicep_pattern: | + // In AGW-001, the autoscaleConfiguration is already present. + // WAF guidance: set minCapacity based on peak compute units / 10 + // Set maxCapacity to 125 (maximum possible) to handle surge traffic + // autoscaleConfiguration: { + // minCapacity: agwMinCapacity // e.g. 2-3 based on baseline + // maxCapacity: 125 + // } +- id: AZ-AGW-006 + severity: recommended + description: Integrate Application Gateway with Key Vault for SSL/TLS certificate management + rationale: 'WAF Security: Key Vault provides stronger security, role separation, managed certificate support, and automatic + renewal/rotation for SSL certificates' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # Add identity and sslCertificates referencing Key Vault to AGW: + # identity = { + # type = "UserAssigned" + # identity_ids = [azapi_resource.agw_identity.id] + # } + # sslCertificates = [ + # { + # name = "ssl-cert" + # properties = { + # keyVaultSecretId = var.key_vault_secret_id + # } + # } + # ] + bicep_pattern: | + // Add identity and sslCertificates referencing Key Vault to AGW: + // identity: { + // type: 'UserAssigned' + // userAssignedIdentities: { + // '${agwIdentity.id}': {} + // } + // } + // sslCertificates: [ + // { + // name: 'ssl-cert' + // properties: { + // keyVaultSecretId: keyVaultSecretId + // } + // } + // ] +- id: AZ-AGW-007 + severity: recommended + description: Configure connection draining on backend HTTP settings + rationale: 'WAF Reliability: Connection draining ensures graceful removal of backend pool members during planned updates, + draining existing connections before taking the backend out of rotation' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # Add to backendHttpSettingsCollection in AGW: + # connectionDraining = { + # enabled = true + # drainTimeoutInSec = 30 + # } + bicep_pattern: | + // Add to backendHttpSettingsCollection in AGW: + // connectionDraining: { + // enabled: true + // drainTimeoutInSec: 30 + // } +- id: AZ-AGW-008 + severity: recommended + description: Use HTTPS backend health probes with valid certificates + rationale: HTTP probes send health check data in plaintext; HTTPS ensures backend communication is encrypted + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # Add to Application Gateway properties + probes = [ + { + name = "https-health-probe" + properties = { + protocol = "Https" + host = var.backend_host + path = "/health" + interval = 30 + timeout = 30 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-399"] + } + } + } + ] + bicep_pattern: | + // Add to Application Gateway properties + probes: [ + { + name: 'https-health-probe' + properties: { + protocol: 'Https' + host: backendHost + path: '/health' + interval: 30 + timeout: 30 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-399'] + } + } + } + ] + prohibitions: + - Do not use HTTP probes for backends that support HTTPS +patterns: +- name: Application Gateway WAF v2 with HTTPS and zone redundancy + description: Full WAF_v2 deployment with autoscaling, WAF policy, and diagnostics + example: | + # See AGW-001 through AGW-008 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy Application Gateway v1 + instead: Use v2 SKU with WAF for autoscaling, zone redundancy, and web protection +- description: Do not run WAF in Detection mode for production + instead: Use Prevention mode to actively block malicious requests +references: +- title: Application Gateway documentation + url: https://learn.microsoft.com/azure/application-gateway/overview +- title: WAF on Application Gateway + url: https://learn.microsoft.com/azure/web-application-firewall/ag/ag-overview +- title: 'WAF: Application Gateway service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-application-gateway +- title: Application Gateway autoscaling + url: https://learn.microsoft.com/azure/application-gateway/application-gateway-autoscaling-zone-redundant +- title: Application Gateway Key Vault integration + url: https://learn.microsoft.com/azure/application-gateway/key-vault-certs diff --git a/azext_prototype/governance/policies/azure/networking/bastion.policy.yaml b/azext_prototype/governance/policies/azure/networking/bastion.policy.yaml new file mode 100644 index 0000000..c776ac3 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/bastion.policy.yaml @@ -0,0 +1,402 @@ +kind: policy +domain: azure-networking +description: Governance policies for Bastion +last_updated: '2026-03-27' +rules: +- id: AZ-BAS-001 + severity: required + description: Deploy Azure Bastion with Standard SKU for production workloads + rationale: Standard SKU provides native client support, IP-based connections, shareable links, and Kerberos auth + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-bastion + description: Standard SKU static public IP for Bastion frontend + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: AzureBastionSubnet + description: Dedicated AzureBastionSubnet with /26 or larger CIDR + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-bastion + description: NSG on AzureBastionSubnet with required Bastion inbound/outbound rules + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-bastion + description: Diagnostic settings routing Bastion session logs to Log Analytics + targets: + - services: + - Microsoft.Network/bastionHosts + terraform_pattern: | + resource "azapi_resource" "bastion" { + type = "Microsoft.Network/bastionHosts@2024-01-01" + name = var.bastion_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Standard" + } + properties = { + ipConfigurations = [ + { + name = "bastion-ip-config" + properties = { + subnet = { + id = var.bastion_subnet_id + } + publicIPAddress = { + id = azapi_resource.bastion_public_ip.id + } + } + } + ] + enableTunneling = true + enableFileCopy = true + enableShareableLink = false + } + } + } + bicep_pattern: | + resource bastion 'Microsoft.Network/bastionHosts@2024-01-01' = { + name: bastionName + location: location + sku: { + name: 'Standard' + } + properties: { + ipConfigurations: [ + { + name: 'bastion-ip-config' + properties: { + subnet: { + id: bastionSubnetId + } + publicIPAddress: { + id: bastionPublicIp.id + } + } + } + ] + enableTunneling: true + enableFileCopy: true + enableShareableLink: false + } + } + prohibitions: + - Do not use Basic SKU for production — it lacks tunneling, file copy, and native client support + - Do not enable shareable links unless explicitly required — they bypass Azure AD conditional access + - Do not deploy Bastion in a subnet other than AzureBastionSubnet + - Do not use a subnet smaller than /26 for AzureBastionSubnet +- id: AZ-BAS-002 + severity: required + description: Create a dedicated AzureBastionSubnet with minimum /26 prefix and required NSG + rationale: Azure Bastion requires a specifically named subnet with minimum size and mandatory NSG rules + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-bastion + description: NSG with required inbound/outbound rules for AzureBastionSubnet + targets: + - services: + - Microsoft.Network/bastionHosts + terraform_pattern: | + resource "azapi_resource" "bastion_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "AzureBastionSubnet" + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.bastion_subnet_prefix + networkSecurityGroup = { + id = azapi_resource.bastion_nsg.id + } + } + } + } + bicep_pattern: | + resource bastionSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: 'AzureBastionSubnet' + properties: { + addressPrefix: bastionSubnetPrefix + networkSecurityGroup: { + id: bastionNsg.id + } + } + } + prohibitions: + - Do not name the subnet anything other than AzureBastionSubnet + - Do not omit NSG from AzureBastionSubnet +- id: AZ-BAS-003 + severity: required + description: Configure NSG on AzureBastionSubnet with mandatory inbound and outbound rules + rationale: Azure Bastion requires specific ports for GatewayManager, HTTPS ingress, and data plane communication + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/bastionHosts + terraform_pattern: | + resource "azapi_resource" "bastion_nsg" { + type = "Microsoft.Network/networkSecurityGroups@2024-01-01" + name = var.bastion_nsg_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + securityRules = [ + { + name = "AllowHttpsInbound" + properties = { + priority = 120 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + sourcePortRange = "*" + destinationPortRange = "443" + sourceAddressPrefix = "Internet" + destinationAddressPrefix = "*" + } + }, + { + name = "AllowGatewayManagerInbound" + properties = { + priority = 130 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + sourcePortRange = "*" + destinationPortRange = "443" + sourceAddressPrefix = "GatewayManager" + destinationAddressPrefix = "*" + } + }, + { + name = "AllowBastionHostCommunication" + properties = { + priority = 150 + direction = "Inbound" + access = "Allow" + protocol = "*" + sourcePortRange = "*" + destinationPortRanges = ["8080", "5701"] + sourceAddressPrefix = "VirtualNetwork" + destinationAddressPrefix = "VirtualNetwork" + } + }, + { + name = "AllowSshRdpOutbound" + properties = { + priority = 100 + direction = "Outbound" + access = "Allow" + protocol = "Tcp" + sourcePortRange = "*" + destinationPortRanges = ["22", "3389"] + sourceAddressPrefix = "*" + destinationAddressPrefix = "VirtualNetwork" + } + }, + { + name = "AllowAzureCloudOutbound" + properties = { + priority = 110 + direction = "Outbound" + access = "Allow" + protocol = "Tcp" + sourcePortRange = "*" + destinationPortRange = "443" + sourceAddressPrefix = "*" + destinationAddressPrefix = "AzureCloud" + } + }, + { + name = "AllowBastionCommunicationOutbound" + properties = { + priority = 120 + direction = "Outbound" + access = "Allow" + protocol = "*" + sourcePortRange = "*" + destinationPortRanges = ["8080", "5701"] + sourceAddressPrefix = "VirtualNetwork" + destinationAddressPrefix = "VirtualNetwork" + } + } + ] + } + } + } + bicep_pattern: | + resource bastionNsg 'Microsoft.Network/networkSecurityGroups@2024-01-01' = { + name: bastionNsgName + location: location + properties: { + securityRules: [ + { + name: 'AllowHttpsInbound' + properties: { + priority: 120 + direction: 'Inbound' + access: 'Allow' + protocol: 'Tcp' + sourcePortRange: '*' + destinationPortRange: '443' + sourceAddressPrefix: 'Internet' + destinationAddressPrefix: '*' + } + } + { + name: 'AllowGatewayManagerInbound' + properties: { + priority: 130 + direction: 'Inbound' + access: 'Allow' + protocol: 'Tcp' + sourcePortRange: '*' + destinationPortRange: '443' + sourceAddressPrefix: 'GatewayManager' + destinationAddressPrefix: '*' + } + } + { + name: 'AllowBastionHostCommunication' + properties: { + priority: 150 + direction: 'Inbound' + access: 'Allow' + protocol: '*' + sourcePortRange: '*' + destinationPortRanges: ['8080', '5701'] + sourceAddressPrefix: 'VirtualNetwork' + destinationAddressPrefix: 'VirtualNetwork' + } + } + { + name: 'AllowSshRdpOutbound' + properties: { + priority: 100 + direction: 'Outbound' + access: 'Allow' + protocol: 'Tcp' + sourcePortRange: '*' + destinationPortRanges: ['22', '3389'] + sourceAddressPrefix: '*' + destinationAddressPrefix: 'VirtualNetwork' + } + } + { + name: 'AllowAzureCloudOutbound' + properties: { + priority: 110 + direction: 'Outbound' + access: 'Allow' + protocol: 'Tcp' + sourcePortRange: '*' + destinationPortRange: '443' + sourceAddressPrefix: '*' + destinationAddressPrefix: 'AzureCloud' + } + } + { + name: 'AllowBastionCommunicationOutbound' + properties: { + priority: 120 + direction: 'Outbound' + access: 'Allow' + protocol: '*' + sourcePortRange: '*' + destinationPortRanges: ['8080', '5701'] + sourceAddressPrefix: 'VirtualNetwork' + destinationAddressPrefix: 'VirtualNetwork' + } + } + ] + } + } + prohibitions: + - Do not omit mandatory GatewayManager inbound rule — Bastion will fail health checks + - Do not allow RDP/SSH inbound from Internet — only Bastion should broker these connections +- id: AZ-BAS-004 + severity: recommended + description: Enable diagnostic settings for Bastion audit and session logs + rationale: Audit logs track who connected to which VM, required for compliance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for Bastion diagnostic logs + targets: + - services: + - Microsoft.Network/bastionHosts + terraform_pattern: | + resource "azapi_resource" "bastion_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-bastion" + parent_id = azapi_resource.bastion.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "BastionAuditLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource bastionDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-bastion' + scope: bastion + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'BastionAuditLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not skip BastionAuditLogs — they are essential for session tracking and compliance +patterns: +- name: Azure Bastion Standard with full security + description: Standard SKU Bastion with dedicated subnet, NSG, and diagnostics + example: | + # See BAS-001 through BAS-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not expose VM RDP/SSH ports directly to the internet + instead: Use Azure Bastion as a managed jump host for all remote access +- description: Do not deploy Bastion without an NSG on AzureBastionSubnet + instead: Apply NSG with mandatory Bastion rules per Microsoft documentation +references: +- title: Azure Bastion documentation + url: https://learn.microsoft.com/azure/bastion/bastion-overview +- title: NSG rules for Azure Bastion + url: https://learn.microsoft.com/azure/bastion/bastion-nsg diff --git a/azext_prototype/governance/policies/azure/networking/cdn.policy.yaml b/azext_prototype/governance/policies/azure/networking/cdn.policy.yaml new file mode 100644 index 0000000..ea82ba1 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/cdn.policy.yaml @@ -0,0 +1,292 @@ +kind: policy +domain: azure-networking +description: Governance policies for Cdn +last_updated: '2026-03-27' +rules: +- id: AZ-CDN-001 + severity: required + description: Deploy Azure CDN Standard profile with HTTPS enforcement and optimized caching + rationale: CDN accelerates content delivery globally; HTTPS enforcement prevents content interception + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Cdn/profiles/endpoints@2024-02-01 + name: cdn-endpoint + description: CDN endpoint with HTTPS enforcement and caching rules + terraform_pattern: | + resource "azapi_resource" "cdn_endpoint" { + type = "Microsoft.Cdn/profiles/endpoints@2024-02-01" + name = var.endpoint_name + location = "global" + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + isHttpAllowed = false + isHttpsAllowed = true + isCompressionEnabled = true + contentTypesToCompress = [ + "text/plain", + "text/html", + "text/css", + "text/javascript", + "application/javascript", + "application/json", + "application/xml", + "image/svg+xml" + ] + originHostHeader = var.origin_host_name + origins = [ + { + name = "primary-origin" + properties = { + hostName = var.origin_host_name + httpPort = 80 + httpsPort = 443 + enabled = true + } + } + ] + queryStringCachingBehavior = "IgnoreQueryString" + optimizationType = "GeneralWebDelivery" + deliveryPolicy = { + rules = [ + { + name = "HttpsRedirect" + order = 1 + conditions = [ + { + name = "RequestScheme" + parameters = { + typeName = "DeliveryRuleRequestSchemeConditionParameters" + matchValues = ["HTTP"] + operator = "Equal" + negateCondition = false + } + } + ] + actions = [ + { + name = "UrlRedirect" + parameters = { + typeName = "DeliveryRuleUrlRedirectActionParameters" + redirectType = "Found" + destinationProtocol = "Https" + } + } + ] + } + ] + } + } + } + } + bicep_pattern: | + resource cdnEndpoint 'Microsoft.Cdn/profiles/endpoints@2024-02-01' = { + name: endpointName + parent: cdnProfile + location: 'global' + properties: { + isHttpAllowed: false + isHttpsAllowed: true + isCompressionEnabled: true + contentTypesToCompress: [ + 'text/plain' + 'text/html' + 'text/css' + 'text/javascript' + 'application/javascript' + 'application/json' + 'application/xml' + 'image/svg+xml' + ] + originHostHeader: originHostName + origins: [ + { + name: 'primary-origin' + properties: { + hostName: originHostName + httpPort: 80 + httpsPort: 443 + enabled: true + } + } + ] + queryStringCachingBehavior: 'IgnoreQueryString' + optimizationType: 'GeneralWebDelivery' + deliveryPolicy: { + rules: [ + { + name: 'HttpsRedirect' + order: 1 + conditions: [ + { + name: 'RequestScheme' + parameters: { + typeName: 'DeliveryRuleRequestSchemeConditionParameters' + matchValues: ['HTTP'] + operator: 'Equal' + negateCondition: false + } + } + ] + actions: [ + { + name: 'UrlRedirect' + parameters: { + typeName: 'DeliveryRuleUrlRedirectActionParameters' + redirectType: 'Found' + destinationProtocol: 'Https' + } + } + ] + } + ] + } + } + } + - type: Microsoft.Cdn/profiles/endpoints/customDomains@2024-02-01 + name: custom-domain + description: Custom domain with managed HTTPS certificate for branded content delivery + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-cdn + description: Diagnostic settings for CDN access logs and core analytics + terraform_pattern: | + resource "azapi_resource" "diag_cdn" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.cdn_profile_name}" + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagCdn 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${cdnProfileName}' + scope: cdnProfile + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Cdn/profiles + terraform_pattern: | + resource "azapi_resource" "cdn_profile" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.cdn_profile_name + location = "global" + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_Microsoft" # "Standard_Microsoft", "Standard_Akamai", "Standard_Verizon", "Premium_Verizon" + } + properties = { + originResponseTimeoutSeconds = 60 + } + } + } + bicep_pattern: | + resource cdnProfile 'Microsoft.Cdn/profiles@2024-02-01' = { + name: cdnProfileName + location: 'global' + sku: { + name: 'Standard_Microsoft' + } + properties: { + originResponseTimeoutSeconds: 60 + } + } + prohibitions: + - Never set isHttpAllowed to true without an HTTPS redirect rule + - Never serve content over HTTP without redirecting to HTTPS + - Never use wildcard custom domains without explicit security review + - Never cache authenticated or personalized content — use cache-control headers + - Never expose origin server directly — always serve through CDN endpoint +- id: AZ-CDN-002 + severity: required + description: Enforce HTTPS-only delivery with HTTP-to-HTTPS redirect + rationale: HTTP content delivery is subject to interception and modification (content injection) + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +- id: AZ-CDN-003 + severity: recommended + description: Enable compression for text-based content types + rationale: Compression reduces bandwidth consumption and improves page load time by 50-70% for text content + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +- id: AZ-CDN-004 + severity: recommended + description: Configure custom domain with managed HTTPS certificate + rationale: Managed certificates auto-renew and eliminate manual certificate management overhead + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +- id: AZ-CDN-005 + severity: recommended + description: Set appropriate cache TTLs and query string caching behavior + rationale: Proper caching configuration maximizes cache hit ratio and reduces origin load + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +patterns: +- name: CDN Standard with HTTPS enforcement and compression + description: CDN profile with HTTPS-only delivery, compression, caching rules, and diagnostic logging +anti_patterns: +- description: Do not allow HTTP content delivery + instead: Set isHttpAllowed to false or configure HTTP-to-HTTPS redirect rule +- description: Do not cache authenticated or user-specific content + instead: Use appropriate Cache-Control headers and bypass caching for authenticated requests +references: +- title: Azure CDN documentation + url: https://learn.microsoft.com/azure/cdn/cdn-overview +- title: CDN caching rules + url: https://learn.microsoft.com/azure/cdn/cdn-caching-rules diff --git a/azext_prototype/governance/policies/azure/networking/ddos-protection.policy.yaml b/azext_prototype/governance/policies/azure/networking/ddos-protection.policy.yaml new file mode 100644 index 0000000..f015473 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/ddos-protection.policy.yaml @@ -0,0 +1,186 @@ +kind: policy +domain: azure-networking +description: Governance policies for Ddos Protection +last_updated: '2026-03-27' +rules: +- id: AZ-DDOS-001 + severity: required + description: Deploy DDoS Protection Plan and associate with all VNets containing public-facing resources + rationale: DDoS Network Protection provides enhanced mitigation beyond Azure's basic infrastructure protection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworks@2024-01-01 + name: VNet DDoS association + description: Associate the DDoS Protection Plan with VNets that have public IP addresses + terraform_pattern: | + resource "azapi_resource" "vnet" { + type = "Microsoft.Network/virtualNetworks@2024-01-01" + name = var.vnet_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + addressSpace = { + addressPrefixes = var.address_prefixes + } + ddosProtectionPlan = { + id = azapi_resource.ddos_plan.id + } + enableDdosProtection = true + subnets = var.subnets + } + } + } + bicep_pattern: | + resource vnet 'Microsoft.Network/virtualNetworks@2024-01-01' = { + name: vnetName + location: location + properties: { + addressSpace: { + addressPrefixes: addressPrefixes + } + ddosProtectionPlan: { + id: ddosPlan.id + } + enableDdosProtection: true + subnets: subnets + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-ddos + description: Diagnostic settings for DDoS mitigation flow logs and attack analytics + - type: Microsoft.Insights/metricAlerts@2018-03-01 + name: alert-ddos + description: Metric alert for DDoS attack notifications on public IP addresses + terraform_pattern: | + resource "azapi_resource" "ddos_alert" { + type = "Microsoft.Insights/metricAlerts@2018-03-01" + name = "alert-ddos-${var.pip_name}" + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + severity = 1 + enabled = true + scopes = [var.public_ip_id] + evaluationFrequency = "PT1M" + windowSize = "PT5M" + criteria = { + "odata.type" = "Microsoft.Azure.Monitor.SingleResourceMultipleMetricCriteria" + allOf = [ + { + name = "DDoSAttack" + metricName = "IfUnderDDoSAttack" + metricNamespace = "Microsoft.Network/publicIPAddresses" + operator = "GreaterThan" + threshold = 0 + timeAggregation = "Maximum" + criterionType = "StaticThresholdCriterion" + } + ] + } + actions = [ + { + actionGroupId = var.action_group_id + } + ] + } + } + } + bicep_pattern: | + resource ddosAlert 'Microsoft.Insights/metricAlerts@2018-03-01' = { + name: 'alert-ddos-${pipName}' + location: 'global' + properties: { + severity: 1 + enabled: true + scopes: [publicIpId] + evaluationFrequency: 'PT1M' + windowSize: 'PT5M' + criteria: { + 'odata.type': 'Microsoft.Azure.Monitor.SingleResourceMultipleMetricCriteria' + allOf: [ + { + name: 'DDoSAttack' + metricName: 'IfUnderDDoSAttack' + metricNamespace: 'Microsoft.Network/publicIPAddresses' + operator: 'GreaterThan' + threshold: 0 + timeAggregation: 'Maximum' + criterionType: 'StaticThresholdCriterion' + } + ] + } + actions: [ + { + actionGroupId: actionGroupId + } + ] + } + } + targets: + - services: + - Microsoft.Network/ddosProtectionPlans + terraform_pattern: | + resource "azapi_resource" "ddos_plan" { + type = "Microsoft.Network/ddosProtectionPlans@2024-01-01" + name = var.ddos_plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = {} + } + } + bicep_pattern: | + resource ddosPlan 'Microsoft.Network/ddosProtectionPlans@2024-01-01' = { + name: ddosPlanName + location: location + properties: {} + } + prohibitions: + - Never deploy public-facing VNets without DDoS Protection Plan association + - Never set enableDdosProtection to false on VNets with public IP addresses + - Never skip DDoS attack metric alerts — immediate notification is critical +- id: AZ-DDOS-002 + severity: required + description: Configure DDoS attack metric alerts on all public IP addresses + rationale: Immediate notification of DDoS attacks enables rapid response and mitigation tuning + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Network/ddosProtectionPlans +- id: AZ-DDOS-003 + severity: recommended + description: Enable DDoS diagnostic logging for attack analytics and post-incident review + rationale: Diagnostic logs provide attack vectors, dropped packets, and mitigation reports for forensics + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Network/ddosProtectionPlans +patterns: +- name: DDoS Protection with VNet association and alerts + description: DDoS plan associated with VNets, metric alerts on public IPs, and diagnostic logging +anti_patterns: +- description: Do not deploy public-facing services without DDoS Protection + instead: Create a DDoS Protection Plan and associate with all VNets containing public IPs +- description: Do not skip attack notification alerts + instead: Configure metric alerts on IfUnderDDoSAttack for all public IP addresses +references: +- title: Azure DDoS Protection overview + url: https://learn.microsoft.com/azure/ddos-protection/ddos-protection-overview +- title: Configure DDoS diagnostic logging + url: https://learn.microsoft.com/azure/ddos-protection/diagnostic-logging diff --git a/azext_prototype/governance/policies/azure/networking/dns-zones.policy.yaml b/azext_prototype/governance/policies/azure/networking/dns-zones.policy.yaml new file mode 100644 index 0000000..3e84da9 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/dns-zones.policy.yaml @@ -0,0 +1,267 @@ +kind: policy +domain: azure-networking +description: Governance policies for Dns Zones +last_updated: '2026-03-27' +rules: +- id: AZ-DNS-001 + severity: required + description: Use Azure Private DNS Zones for internal name resolution within virtual networks + rationale: Private DNS zones provide name resolution within VNets without exposing DNS records to the internet + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01 + name: link-vnet + description: VNet link enabling DNS resolution from the virtual network + - type: Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-04-01 + name: default + description: DNS zone group auto-registering private endpoint A records + targets: + - services: + - Microsoft.Network/dnsZones + terraform_pattern: | + resource "azapi_resource" "private_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2024-06-01" + name = var.private_dns_zone_name + location = "global" + parent_id = var.resource_group_id + body = {} + } + bicep_pattern: | + resource privateDnsZone 'Microsoft.Network/privateDnsZones@2024-06-01' = { + name: privateDnsZoneName + location: 'global' + } + prohibitions: + - Do not use public DNS zones for internal service discovery + - Do not create private DNS zones without VNet links — they will not resolve +- id: AZ-DNS-002 + severity: required + description: Link Private DNS Zones to all VNets that need resolution + rationale: Without VNet links, VMs and services in the VNet cannot resolve private DNS records + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: parent-zone + description: Parent private DNS zone that the VNet link attaches to + - type: Microsoft.Network/virtualNetworks@2024-01-01 + name: vnet + description: Target virtual network to link to the private DNS zone + targets: + - services: + - Microsoft.Network/dnsZones + terraform_pattern: | + resource "azapi_resource" "dns_vnet_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2024-06-01" + name = var.vnet_link_name + location = "global" + parent_id = azapi_resource.private_dns_zone.id + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + bicep_pattern: | + resource dnsVnetLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2024-06-01' = { + parent: privateDnsZone + name: vnetLinkName + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + prohibitions: + - Do not enable registrationEnabled unless auto-registration of VM records is explicitly needed + - Do not create multiple VNet links to the same VNet for the same zone +- id: AZ-DNS-003 + severity: required + description: Use standard private DNS zone names for Azure private endpoints + rationale: Azure services expect specific zone names for private endpoint resolution (e.g., privatelink.blob.core.windows.net) + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-service + description: Private endpoint for the Azure service requiring DNS resolution + - type: Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01 + name: link-vnet + description: VNet link enabling private DNS zone resolution from the virtual network + targets: + - services: + - Microsoft.Network/dnsZones + terraform_pattern: | + # Standard private DNS zone names for common Azure services: + # Storage Blob: privatelink.blob.core.windows.net + # Storage File: privatelink.file.core.windows.net + # Storage Table: privatelink.table.core.windows.net + # Storage Queue: privatelink.queue.core.windows.net + # SQL Database: privatelink.database.windows.net + # Cosmos DB: privatelink.documents.azure.com + # Key Vault: privatelink.vaultcore.azure.net + # ACR: privatelink.azurecr.io + # Event Hubs: privatelink.servicebus.windows.net + # Service Bus: privatelink.servicebus.windows.net + # IoT Hub: privatelink.azure-devices.net + # Redis: privatelink.redis.cache.windows.net + # App Config: privatelink.azconfig.io + # Synapse: privatelink.sql.azuresynapse.net + + resource "azapi_resource" "pe_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2024-06-01" + name = "privatelink.blob.core.windows.net" + location = "global" + parent_id = var.resource_group_id + body = {} + } + bicep_pattern: | + // Use the correct privatelink zone name for each Azure service + resource peDnsZone 'Microsoft.Network/privateDnsZones@2024-06-01' = { + name: 'privatelink.blob.core.windows.net' + location: 'global' + } + prohibitions: + - Do not use custom zone names for private endpoints — Azure expects standard privatelink.* names + - Do not create duplicate private DNS zones for the same service in the same resource group +- id: AZ-DNS-004 + severity: recommended + description: Configure public DNS zones with appropriate TTL values and DNSSEC when available + rationale: Low TTL enables faster failover; DNSSEC prevents DNS spoofing for public zones + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-dns + description: Diagnostic settings routing DNS query logs to Log Analytics + targets: + - services: + - Microsoft.Network/dnsZones + terraform_pattern: | + resource "azapi_resource" "public_dns_zone" { + type = "Microsoft.Network/dnsZones@2023-07-01-preview" + name = var.domain_name + location = "global" + parent_id = var.resource_group_id + body = { + properties = {} + } + } + + resource "azapi_resource" "dns_a_record" { + type = "Microsoft.Network/dnsZones/A@2023-07-01-preview" + name = var.record_name + parent_id = azapi_resource.public_dns_zone.id + body = { + properties = { + TTL = 300 + ARecords = [ + { + ipv4Address = var.target_ip + } + ] + } + } + } + bicep_pattern: | + resource publicDnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = { + name: domainName + location: 'global' + properties: {} + } + + resource dnsARecord 'Microsoft.Network/dnsZones/A@2023-07-01-preview' = { + parent: publicDnsZone + name: recordName + properties: { + TTL: 300 + ARecords: [ + { + ipv4Address: targetIp + } + ] + } + } + prohibitions: + - Do not set TTL to 0 — it disables caching and increases query load + - Do not create wildcard records unless explicitly required +- id: AZ-DNS-005 + severity: recommended + description: Enable diagnostic settings for DNS zone query logging + rationale: Query logs help with troubleshooting resolution issues and detecting anomalous patterns + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace as destination for DNS zone query logs + targets: + - services: + - Microsoft.Network/dnsZones + terraform_pattern: | + resource "azapi_resource" "dns_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-dns-zone" + parent_id = azapi_resource.public_dns_zone.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource dnsDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-dns-zone' + scope: publicDnsZone + properties: { + workspaceId: logAnalyticsWorkspaceId + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not skip DNS diagnostics in production — resolution failures are hard to debug without logs +patterns: +- name: Private DNS Zone with VNet link and private endpoint + description: Private DNS zone for Azure service private endpoints with VNet resolution + example: | + # See DNS-001 through DNS-005 for complete azapi_resource patterns +anti_patterns: +- description: Do not use public DNS for internal service communication + instead: Use Azure Private DNS Zones linked to your VNet +- description: Do not use custom DNS zone names for Azure private endpoints + instead: Use the standard privatelink.* zone names documented by Microsoft +references: +- title: Azure DNS documentation + url: https://learn.microsoft.com/azure/dns/dns-overview +- title: Azure Private DNS documentation + url: https://learn.microsoft.com/azure/dns/private-dns-overview +- title: Private endpoint DNS configuration + url: https://learn.microsoft.com/azure/private-link/private-endpoint-dns diff --git a/azext_prototype/governance/policies/azure/networking/expressroute.policy.yaml b/azext_prototype/governance/policies/azure/networking/expressroute.policy.yaml new file mode 100644 index 0000000..44f9ec9 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/expressroute.policy.yaml @@ -0,0 +1,271 @@ +kind: policy +domain: azure-networking +description: Governance policies for Expressroute +last_updated: '2026-03-27' +rules: +- id: AZ-ER-001 + severity: required + description: Deploy ExpressRoute circuit with Premium tier for cross-region connectivity or large route tables + rationale: Standard tier limits to 4000 routes and single geopolitical region; Premium required for global reach + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworkGateways@2023-04-01 + name: ergw + description: ExpressRoute gateway with ErGw2AZ or higher + - type: Microsoft.Network/connections@2023-04-01 + name: erc-connection + description: ExpressRoute connection to gateway + - type: Microsoft.Network/expressRouteCircuits/peerings@2023-04-01 + name: private-peering + description: Private peering configuration + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-udr + description: Route logs to Log Analytics + targets: + - services: + - Microsoft.Network/expressRouteCircuits + terraform_pattern: | + resource "azapi_resource" "expressroute_circuit" { + type = "Microsoft.Network/expressRouteCircuits@2024-01-01" + name = var.circuit_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Premium_MeteredData" + tier = "Premium" + family = "MeteredData" + } + properties = { + serviceProviderProperties = { + serviceProviderName = var.provider_name + peeringLocation = var.peering_location + bandwidthInMbps = var.bandwidth_mbps + } + allowClassicOperations = false + } + } + } + bicep_pattern: | + resource expressRouteCircuit 'Microsoft.Network/expressRouteCircuits@2024-01-01' = { + name: circuitName + location: location + sku: { + name: 'Premium_MeteredData' + tier: 'Premium' + family: 'MeteredData' + } + properties: { + serviceProviderProperties: { + serviceProviderName: providerName + peeringLocation: peeringLocation + bandwidthInMbps: bandwidthMbps + } + allowClassicOperations: false + } + } + prohibitions: + - Do not enable allowClassicOperations — classic deployment model is deprecated + - Do not use Standard tier if connecting across geopolitical regions + - Do not share circuit service keys — treat them as secrets +- id: AZ-ER-002 + severity: required + description: Deploy ExpressRoute Gateway with ErGw2AZ or higher SKU for zone redundancy + rationale: AZ SKUs provide zone redundancy; ErGw1Az has limited throughput for production workloads + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-gw + description: Standard SKU static for ER gateway + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: GatewaySubnet + description: GatewaySubnet with /27 or larger + targets: + - services: + - Microsoft.Network/expressRouteCircuits + terraform_pattern: | + resource "azapi_resource" "er_gateway" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.er_gateway_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + gatewayType = "ExpressRoute" + sku = { + name = "ErGw2AZ" + tier = "ErGw2AZ" + } + ipConfigurations = [ + { + name = "erGatewayConfig" + properties = { + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.gateway_subnet_id + } + publicIPAddress = { + id = azapi_resource.er_pip.id + } + } + } + ] + } + } + } + bicep_pattern: | + resource erGateway 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: erGatewayName + location: location + properties: { + gatewayType: 'ExpressRoute' + sku: { + name: 'ErGw2AZ' + tier: 'ErGw2AZ' + } + ipConfigurations: [ + { + name: 'erGatewayConfig' + properties: { + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: gatewaySubnetId + } + publicIPAddress: { + id: erPip.id + } + } + } + ] + } + } + prohibitions: + - Do not use non-AZ SKUs for production ExpressRoute gateways + - Do not colocate VPN and ExpressRoute gateways in the same GatewaySubnet without planning +- id: AZ-ER-003 + severity: required + description: Configure private peering with BFD enabled for fast failover + rationale: BFD detects link failures in sub-second intervals vs BGP hold timer defaults of 180 seconds + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/expressRouteCircuits@2023-04-01 + name: erc + description: Parent circuit + targets: + - services: + - Microsoft.Network/expressRouteCircuits + terraform_pattern: | + resource "azapi_resource" "er_private_peering" { + type = "Microsoft.Network/expressRouteCircuits/peerings@2024-01-01" + name = "AzurePrivatePeering" + parent_id = azapi_resource.expressroute_circuit.id + body = { + properties = { + peeringType = "AzurePrivatePeering" + peerASN = var.peer_asn + primaryPeerAddressPrefix = var.primary_peer_prefix + secondaryPeerAddressPrefix = var.secondary_peer_prefix + vlanId = var.vlan_id + } + } + } + bicep_pattern: | + resource erPrivatePeering 'Microsoft.Network/expressRouteCircuits/peerings@2024-01-01' = { + parent: expressRouteCircuit + name: 'AzurePrivatePeering' + properties: { + peeringType: 'AzurePrivatePeering' + peerASN: peerAsn + primaryPeerAddressPrefix: primaryPeerPrefix + secondaryPeerAddressPrefix: secondaryPeerPrefix + vlanId: vlanId + } + } + prohibitions: + - Do not use Microsoft peering for internal traffic — use private peering + - Do not use overlapping address prefixes between primary and secondary paths +- id: AZ-ER-004 + severity: recommended + description: Enable diagnostic settings for ExpressRoute circuit and gateway + rationale: Monitor BGP route advertisements, circuit availability, and throughput metrics + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/expressRouteCircuits + terraform_pattern: | + resource "azapi_resource" "er_circuit_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-expressroute" + parent_id = azapi_resource.expressroute_circuit.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "PeeringRouteLog" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource erCircuitDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-expressroute' + scope: expressRouteCircuit + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'PeeringRouteLog' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit PeeringRouteLog — it tracks BGP route changes +patterns: +- name: ExpressRoute circuit with private peering and gateway + description: Premium ExpressRoute circuit with private peering and zone-redundant gateway + example: | + # See ER-001 through ER-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use ExpressRoute without a redundant circuit or VPN failover + instead: Configure a secondary ExpressRoute circuit or S2S VPN as backup +- description: Do not expose ExpressRoute service keys in source control + instead: Store service keys in Key Vault and reference via secure parameters +references: +- title: ExpressRoute documentation + url: https://learn.microsoft.com/azure/expressroute/expressroute-introduction +- title: ExpressRoute high availability + url: https://learn.microsoft.com/azure/expressroute/designing-for-high-availability-with-expressroute diff --git a/azext_prototype/governance/policies/azure/networking/firewall.policy.yaml b/azext_prototype/governance/policies/azure/networking/firewall.policy.yaml new file mode 100644 index 0000000..3153ccc --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/firewall.policy.yaml @@ -0,0 +1,350 @@ +kind: policy +domain: azure-networking +description: Governance policies for Firewall +last_updated: '2026-03-27' +rules: +- id: AZ-FW-001 + severity: required + description: Deploy Azure Firewall Premium with threat intelligence, IDPS, and TLS inspection + rationale: Premium SKU provides signature-based IDPS, TLS inspection, and URL filtering beyond Standard capabilities + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/firewallPolicies@2024-01-01 + name: fw-policy + description: Firewall policy with IDPS, TLS inspection, and threat intelligence enabled + terraform_pattern: | + resource "azapi_resource" "firewall_policy" { + type = "Microsoft.Network/firewallPolicies@2024-01-01" + name = "fwpol-${var.firewall_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + tier = "Premium" + } + threatIntelMode = "Deny" + threatIntelWhitelist = { + fqdns = [] + ipAddresses = [] + } + intrusionDetection = { + mode = "Deny" + configuration = { + signatureOverrides = [] + bypassTrafficSettings = [] + } + } + transportSecurity = { + certificateAuthority = { + keyVaultSecretId = var.tls_ca_secret_id + name = var.tls_ca_name + } + } + dnsSettings = { + enableProxy = true + servers = var.dns_servers + } + } + } + } + bicep_pattern: | + resource firewallPolicy 'Microsoft.Network/firewallPolicies@2024-01-01' = { + name: 'fwpol-${firewallName}' + location: location + properties: { + sku: { + tier: 'Premium' + } + threatIntelMode: 'Deny' + intrusionDetection: { + mode: 'Deny' + configuration: { + signatureOverrides: [] + bypassTrafficSettings: [] + } + } + transportSecurity: { + certificateAuthority: { + keyVaultSecretId: tlsCaSecretId + name: tlsCaName + } + } + dnsSettings: { + enableProxy: true + servers: dnsServers + } + } + } + - type: Microsoft.Network/publicIPAddresses@2024-01-01 + name: pip-fw + description: Zone-redundant public IP for Azure Firewall + terraform_pattern: | + resource "azapi_resource" "firewall_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.firewall_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + tier = "Regional" + } + properties = { + publicIPAllocationMethod = "Static" + publicIPAddressVersion = "IPv4" + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource firewallPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${firewallName}' + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + zones: ['1', '2', '3'] + properties: { + publicIPAllocationMethod: 'Static' + publicIPAddressVersion: 'IPv4' + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-fw + description: Diagnostic settings for firewall logs including network rules, application rules, and threat intelligence + terraform_pattern: | + resource "azapi_resource" "diag_fw" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.firewall_name}" + parent_id = azapi_resource.firewall.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagFw 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${firewallName}' + scope: firewall + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Network/azureFirewalls + terraform_pattern: | + resource "azapi_resource" "firewall" { + type = "Microsoft.Network/azureFirewalls@2024-01-01" + name = var.firewall_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + name = "AZFW_VNet" + tier = "Premium" + } + ipConfigurations = [ + { + name = "fw-ipconfig" + properties = { + subnet = { + id = var.firewall_subnet_id # Must be named "AzureFirewallSubnet" + } + publicIPAddress = { + id = var.firewall_pip_id + } + } + } + ] + firewallPolicy = { + id = azapi_resource.firewall_policy.id + } + threatIntelMode = "Deny" + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource firewall 'Microsoft.Network/azureFirewalls@2024-01-01' = { + name: firewallName + location: location + zones: ['1', '2', '3'] + properties: { + sku: { + name: 'AZFW_VNet' + tier: 'Premium' + } + ipConfigurations: [ + { + name: 'fw-ipconfig' + properties: { + subnet: { + id: firewallSubnetId + } + publicIPAddress: { + id: firewallPipId + } + } + } + ] + firewallPolicy: { + id: firewallPolicy.id + } + threatIntelMode: 'Deny' + } + } + prohibitions: + - Never deploy Azure Firewall without a firewall policy — always use policy-based management + - Never set threatIntelMode to Off — use Alert or Deny + - Never deploy without zone redundancy (zones 1, 2, 3) + - Never use Basic SKU public IP — use Standard SKU + - Never use the AzureFirewallSubnet for any resources other than Azure Firewall + - Never hardcode Key Vault secret IDs for TLS certificates +- id: AZ-FW-002 + severity: required + description: Deploy in zone-redundant configuration across all three availability zones + rationale: Zone redundancy ensures firewall availability during zone failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-003 + severity: required + description: Enable DNS proxy on the firewall policy for FQDN-based network rules + rationale: DNS proxy is required for FQDN filtering in network rules and supports private DNS resolution + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-004 + severity: recommended + description: Organize rules into rule collection groups by function (infra, app, network) + rationale: Structured rule organization improves manageability and reduces rule processing time + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-005 + severity: recommended + description: Use structured firewall log format and send to Log Analytics + rationale: 'WAF Operational Excellence: Structured logs make data easy to search, filter, and analyze; latest monitoring + tools require this format' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Network/azureFirewalls + prohibitions: + - Do not enable both structured and legacy diagnostic log formats simultaneously +- id: AZ-FW-006 + severity: recommended + description: Monitor SNAT port utilization, firewall health state, throughput, and latency probe metrics + rationale: 'WAF Reliability: These metrics detect when service state degrades, enabling proactive measures to prevent failures' + applies_to: + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-007 + severity: recommended + description: Configure at least 5 public IP addresses for deployments susceptible to SNAT port exhaustion + rationale: 'WAF Performance: Each public IP provides 2,496 SNAT ports per backend VMSS instance; 5 IPs increase available + ports fivefold' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-008 + severity: recommended + description: Use policy analytics dashboard to identify and optimize firewall policies + rationale: 'WAF Performance: Policy analytics identifies potential problems like meeting policy limits, improper rules, + and improper IP groups usage, improving security posture and rule-processing performance' + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Network/azureFirewalls +- id: AZ-FW-009 + severity: recommended + description: Place frequently used rules early in rule collection groups to optimize latency + rationale: 'WAF Performance: Azure Firewall processes rules by priority; placing frequently-hit rules first reduces processing + latency for common traffic patterns' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/azureFirewalls +patterns: +- name: Azure Firewall Premium with IDPS and TLS inspection + description: Hub firewall with Premium policy, threat intelligence in Deny mode, and zone-redundant deployment +anti_patterns: +- description: Do not deploy firewall without a dedicated firewall policy + instead: Always create a firewallPolicy resource and reference it from the firewall +- description: Do not set threat intelligence to Off + instead: Set threatIntelMode to Deny for maximum protection +references: +- title: Azure Firewall documentation + url: https://learn.microsoft.com/azure/firewall/overview +- title: Azure Firewall Premium features + url: https://learn.microsoft.com/azure/firewall/premium-features +- title: 'WAF: Azure Firewall service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-firewall +- title: Azure Firewall monitoring + url: https://learn.microsoft.com/azure/firewall/monitor-firewall +- title: Azure Firewall policy analytics + url: https://learn.microsoft.com/azure/firewall/policy-analytics diff --git a/azext_prototype/governance/policies/azure/networking/load-balancer.policy.yaml b/azext_prototype/governance/policies/azure/networking/load-balancer.policy.yaml new file mode 100644 index 0000000..ed69482 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/load-balancer.policy.yaml @@ -0,0 +1,337 @@ +kind: policy +domain: azure-networking +description: Governance policies for Load Balancer +last_updated: '2026-03-27' +rules: +- id: AZ-LB-001 + severity: required + description: Deploy Load Balancer with Standard SKU — Basic SKU is being retired + rationale: Basic LB lacks zone redundancy, SLA, backend pool flexibility, and will be retired September 2025 + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-lb + description: Standard SKU static for public LB, omit for internal LB + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-resource + description: Required for Standard LB backends — no default allow + - type: Microsoft.Network/loadBalancers/outboundRules@2023-04-01 + name: outbound-rule + description: Explicit outbound if disableOutboundSnat is true + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-metrics + description: Route metrics to Log Analytics + targets: + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + resource "azapi_resource" "load_balancer" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Standard" + tier = "Regional" + } + properties = { + frontendIPConfigurations = [ + { + name = "frontend" + properties = { + subnet = { + id = var.frontend_subnet_id + } + privateIPAllocationMethod = "Dynamic" + } + } + ] + backendAddressPools = [ + { + name = "backend-pool" + } + ] + probes = [ + { + name = "health-probe" + properties = { + protocol = "Tcp" + port = 443 + intervalInSeconds = 5 + numberOfProbes = 2 + probeThreshold = 2 + } + } + ] + loadBalancingRules = [ + { + name = "https-rule" + properties = { + frontendIPConfiguration = { + id = "[concat(resourceId('Microsoft.Network/loadBalancers', variables('lbName')), '/frontendIPConfigurations/frontend')]" + } + backendAddressPool = { + id = "[concat(resourceId('Microsoft.Network/loadBalancers', variables('lbName')), '/backendAddressPools/backend-pool')]" + } + probe = { + id = "[concat(resourceId('Microsoft.Network/loadBalancers', variables('lbName')), '/probes/health-probe')]" + } + protocol = "Tcp" + frontendPort = 443 + backendPort = 443 + enableFloatingIP = false + idleTimeoutInMinutes = 4 + enableTcpReset = true + disableOutboundSnat = true + } + } + ] + } + } + } + bicep_pattern: | + resource loadBalancer 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + properties: { + frontendIPConfigurations: [ + { + name: 'frontend' + properties: { + subnet: { + id: frontendSubnetId + } + privateIPAllocationMethod: 'Dynamic' + } + } + ] + backendAddressPools: [ + { + name: 'backend-pool' + } + ] + probes: [ + { + name: 'health-probe' + properties: { + protocol: 'Tcp' + port: 443 + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + ] + loadBalancingRules: [ + { + name: 'https-rule' + properties: { + frontendIPConfiguration: { + id: resourceId('Microsoft.Network/loadBalancers/frontendIPConfigurations', lbName, 'frontend') + } + backendAddressPool: { + id: resourceId('Microsoft.Network/loadBalancers/backendAddressPools', lbName, 'backend-pool') + } + probe: { + id: resourceId('Microsoft.Network/loadBalancers/probes', lbName, 'health-probe') + } + protocol: 'Tcp' + frontendPort: 443 + backendPort: 443 + enableFloatingIP: false + idleTimeoutInMinutes: 4 + enableTcpReset: true + disableOutboundSnat: true + } + } + ] + } + } + prohibitions: + - Do not use Basic SKU — it is being retired and lacks SLA + - Do not mix Basic and Standard SKU resources in the same backend pool + - Do not leave disableOutboundSnat as false unless you explicitly need implicit SNAT + - Do not use HTTP probes for health checks unless the backend requires it — prefer Tcp or Https +- id: AZ-LB-002 + severity: required + description: Enable TCP reset on idle timeout for all load balancing rules + rationale: TCP reset on idle prevents half-open connections that cause application errors + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # Set enableTcpReset = true in loadBalancingRules properties + # See LB-001 terraform_pattern for full example + bicep_pattern: | + // Set enableTcpReset: true in loadBalancingRules properties + // See LB-001 bicep_pattern for full example + prohibitions: + - Do not set enableTcpReset to false — half-open connections degrade reliability +- id: AZ-LB-003 + severity: recommended + description: Use explicit outbound rules instead of implicit SNAT for outbound connectivity + rationale: Implicit SNAT has port exhaustion risks; explicit outbound rules give control over SNAT ports + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-outbound + description: Dedicated outbound public IP + - type: Microsoft.Network/natGateways@2023-04-01 + name: nat-gw + description: Alternative — use NAT Gateway instead of outbound rules + targets: + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + resource "azapi_resource" "lb_outbound_rule" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + outboundRules = [ + { + name = "outbound-rule" + properties = { + frontendIPConfigurations = [ + { + id = var.outbound_frontend_id + } + ] + backendAddressPool = { + id = var.backend_pool_id + } + protocol = "All" + enableTcpReset = true + idleTimeoutInMinutes = 4 + allocatedOutboundPorts = 1024 + } + } + ] + } + } + } + bicep_pattern: | + // Add outboundRules to the load balancer properties + outboundRules: [ + { + name: 'outbound-rule' + properties: { + frontendIPConfigurations: [ + { + id: outboundFrontendId + } + ] + backendAddressPool: { + id: backendPoolId + } + protocol: 'All' + enableTcpReset: true + idleTimeoutInMinutes: 4 + allocatedOutboundPorts: 1024 + } + } + ] + prohibitions: + - Do not rely on implicit SNAT for production workloads +- id: AZ-LB-004 + severity: recommended + description: Enable diagnostic settings for Load Balancer health probe and SNAT metrics + rationale: Monitor backend health, SNAT port utilization, and data path availability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + resource "azapi_resource" "lb_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-load-balancer" + parent_id = azapi_resource.load_balancer.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "LoadBalancerAlertEvent" + enabled = true + }, + { + category = "LoadBalancerProbeHealthStatus" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource lbDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-load-balancer' + scope: loadBalancer + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'LoadBalancerAlertEvent' + enabled: true + } + { + category: 'LoadBalancerProbeHealthStatus' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit health probe status logs — they are critical for diagnosing backend issues +patterns: +- name: Internal Standard Load Balancer with health probes + description: Standard internal LB with TCP health probes and explicit outbound rules + example: | + # See LB-001 through LB-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use Basic Load Balancer for new deployments + instead: Always use Standard SKU — Basic is being retired +- description: Do not rely on implicit SNAT for production outbound connectivity + instead: Use explicit outbound rules or NAT Gateway for deterministic SNAT +references: +- title: Azure Load Balancer documentation + url: https://learn.microsoft.com/azure/load-balancer/load-balancer-overview +- title: Standard Load Balancer and outbound connections + url: https://learn.microsoft.com/azure/load-balancer/load-balancer-outbound-connections diff --git a/azext_prototype/governance/policies/azure/networking/nat-gateway.policy.yaml b/azext_prototype/governance/policies/azure/networking/nat-gateway.policy.yaml new file mode 100644 index 0000000..80cc1e2 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/nat-gateway.policy.yaml @@ -0,0 +1,218 @@ +kind: policy +domain: azure-networking +description: Governance policies for Nat Gateway +last_updated: '2026-03-27' +rules: +- id: AZ-NAT-001 + severity: required + description: Use Standard SKU for NAT Gateway with zone-redundant public IP + rationale: Standard SKU is the only supported SKU; zone redundancy ensures high availability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-resource + description: Standard SKU, static allocation, zone-redundant + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-nat + description: Associate NAT gateway with subnet + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-metrics + description: Route metrics to Log Analytics + targets: + - services: + - Microsoft.Network/natGateways + terraform_pattern: | + resource "azapi_resource" "nat_gateway" { + type = "Microsoft.Network/natGateways@2024-01-01" + name = var.nat_gateway_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Standard" + } + properties = { + idleTimeoutInMinutes = 4 + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource natGateway 'Microsoft.Network/natGateways@2024-01-01' = { + name: natGatewayName + location: location + sku: { + name: 'Standard' + } + zones: ['1', '2', '3'] + properties: { + idleTimeoutInMinutes: 4 + publicIpAddresses: [ + { id: publicIp.id } + ] + } + } + prohibitions: + - Do not use Basic SKU public IPs — NAT Gateway requires Standard SKU + - Do not set idleTimeoutInMinutes above 120 — causes connection tracking overhead + - Do not associate NAT Gateway with subnets that already have instance-level public IPs for outbound +- id: AZ-NAT-002 + severity: required + description: Associate NAT Gateway with a Standard SKU static public IP address + rationale: NAT Gateway only works with Standard SKU static public IPs; dynamic allocation is not supported + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/natGateways@2023-04-01 + name: nat-gw + description: Parent NAT gateway resource + targets: + - services: + - Microsoft.Network/natGateways + terraform_pattern: | + resource "azapi_resource" "nat_public_ip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = var.nat_public_ip_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Standard" + tier = "Regional" + } + properties = { + publicIPAllocationMethod = "Static" + publicIPAddressVersion = "IPv4" + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource natPublicIp 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: natPublicIpName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + zones: ['1', '2', '3'] + properties: { + publicIPAllocationMethod: 'Static' + publicIPAddressVersion: 'IPv4' + } + } + prohibitions: + - Do not use Dynamic allocation — NAT Gateway requires Static + - Do not use Basic SKU public IPs with NAT Gateway +- id: AZ-NAT-003 + severity: recommended + description: Associate NAT Gateway with private subnets for controlled outbound connectivity + rationale: Subnets without NAT Gateway or other outbound mechanism lose internet access when default outbound is retired + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-resource + description: NSG on subnet for inbound filtering + targets: + - services: + - Microsoft.Network/natGateways + terraform_pattern: | + resource "azapi_resource" "subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = var.subnet_name + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.subnet_prefix + natGateway = { + id = azapi_resource.nat_gateway.id + } + } + } + } + bicep_pattern: | + resource subnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: subnetName + properties: { + addressPrefix: subnetPrefix + natGateway: { + id: natGateway.id + } + } + } + prohibitions: + - Do not assign NAT Gateway to GatewaySubnet — use on application subnets only +- id: AZ-NAT-004 + severity: recommended + description: Enable diagnostic settings for NAT Gateway metrics + rationale: Monitor SNAT port utilization, packet counts, and dropped packets for capacity planning + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/natGateways + terraform_pattern: | + resource "azapi_resource" "nat_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-nat-gateway" + parent_id = azapi_resource.nat_gateway.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource natDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-nat-gateway' + scope: natGateway + properties: { + workspaceId: logAnalyticsWorkspaceId + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit diagnostic settings — SNAT exhaustion is undetectable without metrics +patterns: +- name: NAT Gateway with zone-redundant public IP + description: Standard NAT Gateway associated with a zone-redundant static public IP and subnet + example: | + # Deploy NAT Gateway with Standard public IP and subnet association + # See NAT-001 through NAT-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not rely on default outbound access for internet connectivity + instead: Use NAT Gateway for deterministic, scalable outbound SNAT +- description: Do not attach multiple NAT Gateways to the same subnet + instead: Use a single NAT Gateway with multiple public IPs for scale +references: +- title: Azure NAT Gateway documentation + url: https://learn.microsoft.com/azure/nat-gateway/nat-overview +- title: NAT Gateway metrics and alerts + url: https://learn.microsoft.com/azure/nat-gateway/nat-metrics diff --git a/azext_prototype/governance/policies/azure/networking/network-interface.policy.yaml b/azext_prototype/governance/policies/azure/networking/network-interface.policy.yaml new file mode 100644 index 0000000..6af2410 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/network-interface.policy.yaml @@ -0,0 +1,246 @@ +kind: policy +domain: azure-networking +description: Governance policies for Network Interface +last_updated: '2026-03-27' +rules: +- id: AZ-NIC-001 + severity: required + description: Associate every NIC with a Network Security Group + rationale: NICs without NSGs allow all inbound and outbound traffic by default + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-resource + description: NSG with least-privilege rules + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-resource + description: Target subnet + targets: + - services: + - Microsoft.Network/networkInterfaces + terraform_pattern: | + resource "azapi_resource" "nic" { + type = "Microsoft.Network/networkInterfaces@2024-01-01" + name = var.nic_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + } + } + ] + networkSecurityGroup = { + id = var.nsg_id + } + enableAcceleratedNetworking = true + } + } + } + bicep_pattern: | + resource nic 'Microsoft.Network/networkInterfaces@2024-01-01' = { + name: nicName + location: location + properties: { + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: subnetId + } + } + } + ] + networkSecurityGroup: { + id: nsgId + } + enableAcceleratedNetworking: true + } + } + prohibitions: + - Do not deploy NICs without NSG association + - Do not associate public IPs directly to NICs — use Bastion or internal LB +- id: AZ-NIC-002 + severity: required + description: Do not assign public IP addresses directly to network interfaces + rationale: Direct public IP assignment bypasses centralized ingress controls and exposes the VM to the internet + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.Network/bastionHosts@2023-04-01 + name: bas-mgmt + description: For management access instead of public IPs + - type: Microsoft.Network/loadBalancers@2023-04-01 + name: lb + description: For application traffic instead of public IPs + targets: + - services: + - Microsoft.Network/networkInterfaces + terraform_pattern: | + # ipConfigurations should NOT include publicIPAddress + resource "azapi_resource" "nic_internal" { + type = "Microsoft.Network/networkInterfaces@2024-01-01" + name = var.nic_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + } + } + ] + networkSecurityGroup = { + id = var.nsg_id + } + } + } + } + bicep_pattern: | + // ipConfigurations should NOT include publicIPAddress + resource nicInternal 'Microsoft.Network/networkInterfaces@2024-01-01' = { + name: nicName + location: location + properties: { + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: subnetId + } + } + } + ] + networkSecurityGroup: { + id: nsgId + } + } + } + prohibitions: + - Do not add publicIPAddress to ipConfigurations + - Do not create NICs with open NSG rules allowing RDP (3389) or SSH (22) from Internet +- id: AZ-NIC-003 + severity: recommended + description: Enable accelerated networking on supported VM sizes + rationale: Accelerated networking provides up to 30Gbps throughput and lower latency via SR-IOV + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/networkInterfaces + terraform_pattern: | + # Set enableAcceleratedNetworking = true in NIC properties + # See NIC-001 terraform_pattern for full example + # Supported on most D/E/F/M-series VMs with 4+ vCPUs + bicep_pattern: | + // Set enableAcceleratedNetworking: true in NIC properties + // See NIC-001 bicep_pattern for full example + // Supported on most D/E/F/M-series VMs with 4+ vCPUs + prohibitions: + - Do not enable accelerated networking on unsupported VM sizes — deployment will fail +- id: AZ-NIC-004 + severity: recommended + description: Use static private IP allocation for infrastructure VMs (domain controllers, DNS servers) + rationale: Dynamic IPs can change on deallocation, breaking dependent services + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/networkInterfaces + terraform_pattern: | + resource "azapi_resource" "nic_static" { + type = "Microsoft.Network/networkInterfaces@2024-01-01" + name = var.nic_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + privateIPAllocationMethod = "Static" + privateIPAddress = var.static_ip + subnet = { + id = var.subnet_id + } + } + } + ] + networkSecurityGroup = { + id = var.nsg_id + } + enableAcceleratedNetworking = true + } + } + } + bicep_pattern: | + resource nicStatic 'Microsoft.Network/networkInterfaces@2024-01-01' = { + name: nicName + location: location + properties: { + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + privateIPAllocationMethod: 'Static' + privateIPAddress: staticIp + subnet: { + id: subnetId + } + } + } + ] + networkSecurityGroup: { + id: nsgId + } + enableAcceleratedNetworking: true + } + } + prohibitions: + - Do not use static IPs outside the subnet address range + - Do not hardcode IP addresses — use variables or parameters +patterns: +- name: Network interface with NSG and accelerated networking + description: Production NIC with mandatory NSG, no public IP, and accelerated networking + example: | + # See NIC-001 through NIC-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy NICs without a Network Security Group + instead: Always associate an NSG with every NIC or its subnet +- description: Do not assign public IP addresses to NICs + instead: Use Azure Bastion for management and internal load balancers for application access +references: +- title: Network interface overview + url: https://learn.microsoft.com/azure/virtual-network/virtual-network-network-interface +- title: Accelerated networking + url: https://learn.microsoft.com/azure/virtual-network/accelerated-networking-overview diff --git a/azext_prototype/governance/policies/azure/networking/private-endpoints.policy.yaml b/azext_prototype/governance/policies/azure/networking/private-endpoints.policy.yaml new file mode 100644 index 0000000..46271b7 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/private-endpoints.policy.yaml @@ -0,0 +1,204 @@ +kind: policy +domain: azure-networking +description: Governance policies for Private Endpoints +last_updated: '2026-03-27' +rules: +- id: AZ-PE-001 + severity: required + description: Every private endpoint must have a Private DNS Zone, VNet Link, and DNS Zone Group + rationale: Without all three components, private endpoint DNS resolution fails and connections fall back to public endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/privateEndpoints + - Microsoft.Network/privateDnsZones + - Microsoft.Network/privateDnsZones/virtualNetworkLinks + - Microsoft.Network/privateEndpoints/privateDnsZoneGroups + terraform_pattern: | + # Step 1: Private Endpoint + resource "azapi_resource" "private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.resource_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.resource_name}" + properties = { + privateLinkServiceId = var.target_resource_id + groupIds = [var.group_id] + } + } + ] + } + } + } + + # Step 2: Private DNS Zone + resource "azapi_resource" "private_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = var.private_dns_zone_name + location = "global" + parent_id = azapi_resource.resource_group.id + } + + # Step 3: VNet Link to DNS Zone + resource "azapi_resource" "private_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + # Step 4: DNS Zone Group on the Private Endpoint + resource "azapi_resource" "pe_dns_zone_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = replace(var.private_dns_zone_name, ".", "-") + properties = { + privateDnsZoneId = azapi_resource.private_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + // Step 1: Private Endpoint + resource privateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${resourceName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${resourceName}' + properties: { + privateLinkServiceId: targetResourceId + groupIds: [ + groupId + ] + } + } + ] + } + } + + // Step 2: Private DNS Zone + resource privateDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: privateDnsZoneName + location: 'global' + } + + // Step 3: VNet Link to DNS Zone + resource privateDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: privateDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + // Step 4: DNS Zone Group on the Private Endpoint + resource peDnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: privateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: replace(privateDnsZoneName, '.', '-') + properties: { + privateDnsZoneId: privateDnsZone.id + } + } + ] + } + } + prohibitions: + - NEVER create a private endpoint without a corresponding Private DNS Zone + - NEVER create a Private DNS Zone without linking it to the VNet + - NEVER omit the privateDnsZoneGroups child resource on the private endpoint + - NEVER place private endpoints in delegated subnets + - NEVER set registrationEnabled to true on PE DNS zone links — only hub DNS zones use auto-registration +- id: AZ-PE-002 + severity: required + description: Use correct Private DNS Zone names for each Azure service + rationale: Each Azure service has a specific private DNS zone name; using the wrong name causes resolution failures + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/privateEndpoints + prohibitions: + - NEVER use a custom DNS zone name — use the exact Azure-defined zone name for each service + - NEVER create duplicate DNS zones for the same service — reuse existing zones across private endpoints +- id: AZ-PE-003 + severity: required + description: 'Use standard naming convention: pe-{resource-name} for private endpoints' + rationale: Consistent naming enables automation and troubleshooting + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/privateEndpoints +- id: AZ-PE-004 + severity: recommended + description: Centralize Private DNS Zones in a shared resource group for multi-resource architectures + rationale: Avoids DNS zone sprawl and simplifies management; all PEs share the same zone per service type + applies_to: + - cloud-architect + targets: + - services: + - Microsoft.Network/privateEndpoints +patterns: +- name: Private Endpoint with DNS Zone and VNet Link + description: 'Complete private endpoint deployment with all four required components: PE, DNS Zone, VNet Link, DNS Zone + Group' +anti_patterns: +- description: Do not create a private endpoint without DNS configuration + instead: Always create DNS Zone + VNet Link + DNS Zone Group alongside every private endpoint +- description: Do not use custom DNS zone names + instead: Use the exact Azure-defined privatelink.*.* zone name for each service +- description: Do not place private endpoints in delegated subnets + instead: Use a dedicated PE subnet (snet-pe) without delegations +references: +- title: Private endpoint DNS integration + url: https://learn.microsoft.com/azure/private-link/private-endpoint-dns +- title: Private DNS zone values + url: https://learn.microsoft.com/azure/private-link/private-endpoint-dns#azure-services-dns-zone-configuration +- title: Private endpoint overview + url: https://learn.microsoft.com/azure/private-link/private-endpoint-overview diff --git a/azext_prototype/governance/policies/azure/networking/public-ip.policy.yaml b/azext_prototype/governance/policies/azure/networking/public-ip.policy.yaml new file mode 100644 index 0000000..5b869d6 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/public-ip.policy.yaml @@ -0,0 +1,214 @@ +kind: policy +domain: azure-networking +description: Governance policies for Public Ip +last_updated: '2026-03-27' +rules: +- id: AZ-PIP-001 + severity: required + description: Deploy public IP addresses with Standard SKU and static allocation + rationale: Basic SKU is being retired; Standard SKU is zone-aware and required for Standard LB, NAT Gateway, and Bastion + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/ddosProtectionPlans@2023-04-01 + name: ddos-plan + description: DDoS protection for production workloads + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-udr + description: Route logs to Log Analytics + targets: + - services: + - Microsoft.Network/publicIPAddresses + terraform_pattern: | + resource "azapi_resource" "public_ip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = var.pip_name + location = var.location + parent_id = var.resource_group_id + body = { + sku = { + name = "Standard" + tier = "Regional" + } + properties = { + publicIPAllocationMethod = "Static" + publicIPAddressVersion = "IPv4" + ddosSettings = { + protectionMode = "VirtualNetworkInherited" + } + } + zones = ["1", "2", "3"] + } + } + bicep_pattern: | + resource publicIp 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: pipName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + zones: ['1', '2', '3'] + properties: { + publicIPAllocationMethod: 'Static' + publicIPAddressVersion: 'IPv4' + ddosSettings: { + protectionMode: 'VirtualNetworkInherited' + } + } + } + prohibitions: + - Do not use Basic SKU — it is being retired September 2025 + - Do not use Dynamic allocation with Standard SKU for load balancers or NAT gateways + - Do not deploy public IPs without DDoS protection in production +- id: AZ-PIP-002 + severity: required + description: Deploy zone-redundant public IPs for production workloads + rationale: Zone-redundant IPs survive zone failures; zonal IPs are pinned to a single zone + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/publicIPAddresses + terraform_pattern: | + # Set zones = ["1", "2", "3"] for zone-redundant + # See PIP-001 terraform_pattern for full example + bicep_pattern: | + // Set zones: ['1', '2', '3'] for zone-redundant + // See PIP-001 bicep_pattern for full example + prohibitions: + - Do not deploy production public IPs without zone redundancy + - Do not mix zone-redundant IPs with zonal resources — they must be in the same zone or zone-redundant +- id: AZ-PIP-003 + severity: recommended + description: Minimize the use of public IP addresses — prefer private endpoints and internal load balancers + rationale: Every public IP is an attack surface; reduce exposure by using private connectivity + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-04-01 + name: pe-service + description: Replace public endpoints + - type: Microsoft.Network/loadBalancers@2023-04-01 + name: lb-internal + description: Internal LB instead of public + targets: + - services: + - Microsoft.Network/publicIPAddresses + terraform_pattern: | + # Prefer internal load balancers and private endpoints + # Only use public IPs for: + # - Application Gateway / Front Door ingress + # - VPN/ExpressRoute gateways + # - Azure Bastion + # - NAT Gateway for outbound + bicep_pattern: | + // Prefer internal load balancers and private endpoints + // Only use public IPs for: + // - Application Gateway / Front Door ingress + // - VPN/ExpressRoute gateways + // - Azure Bastion + // - NAT Gateway for outbound + prohibitions: + - Do not assign public IPs directly to VMs — use Bastion or internal LB + - Do not assign public IPs to databases, caches, or storage accounts — use private endpoints +- id: AZ-PIP-004 + severity: recommended + description: Enable diagnostic settings for public IP address DDoS and flow logs + rationale: Monitor DDoS mitigation events and traffic patterns for security analysis + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/publicIPAddresses + terraform_pattern: | + resource "azapi_resource" "pip_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-public-ip" + parent_id = azapi_resource.public_ip.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "DDoSProtectionNotifications" + enabled = true + }, + { + category = "DDoSMitigationFlowLogs" + enabled = true + }, + { + category = "DDoSMitigationReports" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource pipDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-public-ip' + scope: publicIp + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'DDoSProtectionNotifications' + enabled: true + } + { + category: 'DDoSMitigationFlowLogs' + enabled: true + } + { + category: 'DDoSMitigationReports' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit DDoS logs on internet-facing public IPs +patterns: +- name: Standard zone-redundant public IP with DDoS diagnostics + description: Production-ready public IP with zone redundancy and DDoS monitoring + example: | + # See PIP-001 through PIP-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use Basic SKU public IPs + instead: Always use Standard SKU — Basic is being retired +- description: Do not assign public IPs directly to virtual machines + instead: Use Azure Bastion for management access and internal load balancers for application traffic +references: +- title: Public IP address overview + url: https://learn.microsoft.com/azure/virtual-network/ip-services/public-ip-addresses +- title: Standard public IP migration + url: https://learn.microsoft.com/azure/virtual-network/ip-services/public-ip-basic-upgrade-guidance diff --git a/azext_prototype/governance/policies/azure/networking/route-tables.policy.yaml b/azext_prototype/governance/policies/azure/networking/route-tables.policy.yaml new file mode 100644 index 0000000..d939b16 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/route-tables.policy.yaml @@ -0,0 +1,197 @@ +kind: policy +domain: azure-networking +description: Governance policies for Route Tables +last_updated: '2026-03-27' +rules: +- id: AZ-UDR-001 + severity: required + description: Disable BGP route propagation on subnets with forced tunneling to an NVA or firewall + rationale: BGP propagation can override UDR next-hops and bypass security inspection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: snet-workload + description: Associate route table with target subnets + - type: Microsoft.Network/azureFirewalls@2023-04-01 + name: azurefirewalls + description: Next-hop target for forced tunneling + targets: + - services: + - Microsoft.Network/routeTables + terraform_pattern: | + resource "azapi_resource" "route_table" { + type = "Microsoft.Network/routeTables@2024-01-01" + name = var.route_table_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + disableBgpRoutePropagation = true + routes = [] + } + } + } + bicep_pattern: | + resource routeTable 'Microsoft.Network/routeTables@2024-01-01' = { + name: routeTableName + location: location + properties: { + disableBgpRoutePropagation: true + routes: [] + } + } + prohibitions: + - Do not leave disableBgpRoutePropagation as false when forcing traffic to an NVA + - Do not create routes with nextHopType 'Internet' in secured subnets — use firewall as next hop +- id: AZ-UDR-002 + severity: required + description: Define explicit routes with valid next-hop types and addresses + rationale: Invalid or missing next-hop addresses cause traffic black-holes + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/routeTables@2023-04-01 + name: rt-default + description: Parent route table + targets: + - services: + - Microsoft.Network/routeTables + terraform_pattern: | + resource "azapi_resource" "route_to_firewall" { + type = "Microsoft.Network/routeTables/routes@2024-01-01" + name = "route-to-firewall" + parent_id = azapi_resource.route_table.id + body = { + properties = { + addressPrefix = "0.0.0.0/0" + nextHopType = "VirtualAppliance" + nextHopIpAddress = var.firewall_private_ip + } + } + } + bicep_pattern: | + resource routeToFirewall 'Microsoft.Network/routeTables/routes@2024-01-01' = { + parent: routeTable + name: 'route-to-firewall' + properties: { + addressPrefix: '0.0.0.0/0' + nextHopType: 'VirtualAppliance' + nextHopIpAddress: firewallPrivateIp + } + } + prohibitions: + - Do not omit nextHopIpAddress when nextHopType is VirtualAppliance + - Do not use hardcoded IP addresses — use variables or references +- id: AZ-UDR-003 + severity: recommended + description: Associate route tables with subnets explicitly in the subnet resource + rationale: Unassociated route tables have no effect on traffic flow + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/networkSecurityGroups@2023-04-01 + name: nsg-resource + description: Always pair UDR with NSG + targets: + - services: + - Microsoft.Network/routeTables + terraform_pattern: | + resource "azapi_resource" "subnet_with_udr" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = var.subnet_name + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.subnet_prefix + routeTable = { + id = azapi_resource.route_table.id + } + networkSecurityGroup = { + id = azapi_resource.nsg.id + } + } + } + } + bicep_pattern: | + resource subnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: subnetName + properties: { + addressPrefix: subnetPrefix + routeTable: { + id: routeTable.id + } + networkSecurityGroup: { + id: nsg.id + } + } + } + prohibitions: + - Do not associate a route table with GatewaySubnet unless specifically required for forced tunneling + - Do not create subnets without both NSG and route table associations +- id: AZ-UDR-004 + severity: recommended + description: Document all custom routes and their purpose with tags + rationale: Route tables can create complex traffic flows that are hard to debug without documentation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/routeTables + terraform_pattern: | + resource "azapi_resource" "route_table_tagged" { + type = "Microsoft.Network/routeTables@2024-01-01" + name = var.route_table_name + location = var.location + parent_id = var.resource_group_id + tags = { + purpose = "force-tunnel-to-firewall" + managed_by = "terraform" + environment = var.environment + } + body = { + properties = { + disableBgpRoutePropagation = true + } + } + } + bicep_pattern: | + resource routeTable 'Microsoft.Network/routeTables@2024-01-01' = { + name: routeTableName + location: location + tags: { + purpose: 'force-tunnel-to-firewall' + managedBy: 'bicep' + environment: environment + } + properties: { + disableBgpRoutePropagation: true + } + } + prohibitions: + - Do not deploy route tables without descriptive tags +patterns: +- name: Forced tunneling via Azure Firewall + description: Route table with 0.0.0.0/0 route to Azure Firewall private IP + example: | + # See UDR-001 through UDR-003 for complete azapi_resource patterns +anti_patterns: +- description: Do not create overlapping routes with different next-hops + instead: Use most-specific prefix matching and validate route precedence +- description: Do not use the None next-hop type to silently drop traffic without logging + instead: Route to a firewall that logs dropped traffic for audit purposes +references: +- title: Virtual network traffic routing + url: https://learn.microsoft.com/azure/virtual-network/virtual-networks-udr-overview +- title: Route table tutorial + url: https://learn.microsoft.com/azure/virtual-network/tutorial-create-route-table-portal diff --git a/azext_prototype/governance/policies/azure/networking/traffic-manager.policy.yaml b/azext_prototype/governance/policies/azure/networking/traffic-manager.policy.yaml new file mode 100644 index 0000000..75650c8 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/traffic-manager.policy.yaml @@ -0,0 +1,256 @@ +kind: policy +domain: azure-networking +description: Governance policies for Traffic Manager +last_updated: '2026-03-27' +rules: +- id: AZ-TM-001 + severity: required + description: Configure Traffic Manager profile with appropriate routing method and HTTPS monitoring + rationale: HTTPS monitoring ensures endpoints are reachable and TLS is functional; routing method must match traffic pattern + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/trafficManagerProfiles/azureEndpoints@2022-04-01 + name: ep-azure + description: Azure endpoint definitions + - type: Microsoft.Network/trafficManagerProfiles/externalEndpoints@2022-04-01 + name: ep-external + description: External endpoint definitions + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-udr + description: Route logs to Log Analytics + targets: + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficManagerProfiles@2022-04-01" + name = var.tm_profile_name + location = "global" + parent_id = var.resource_group_id + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" + dnsConfig = { + relativeName = var.tm_dns_name + ttl = 60 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/health" + intervalInSeconds = 30 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 10 + expectedStatusCodeRanges = [ + { + min = 200 + max = 299 + } + ] + } + } + } + } + bicep_pattern: | + resource trafficManager 'Microsoft.Network/trafficManagerProfiles@2022-04-01' = { + name: tmProfileName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: tmDnsName + ttl: 60 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/health' + intervalInSeconds: 30 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 10 + expectedStatusCodeRanges: [ + { + min: 200 + max: 299 + } + ] + } + } + } + prohibitions: + - Do not use HTTP monitoring — always use HTTPS for health probes + - Do not set TTL higher than 60 seconds for failover scenarios — increases failover time + - Do not use Traffic Manager without health monitoring enabled +- id: AZ-TM-002 + severity: required + description: Configure endpoints with proper priority and geographic constraints + rationale: Endpoint configuration determines traffic distribution and failover behavior + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/trafficManagerProfiles@2022-04-01 + name: tm-profile + description: Parent profile + - type: Microsoft.Web/sites@2023-12-01 + name: app + description: Target resources + targets: + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + resource "azapi_resource" "tm_endpoint" { + type = "Microsoft.Network/trafficManagerProfiles/azureEndpoints@2022-04-01" + name = var.endpoint_name + parent_id = azapi_resource.traffic_manager.id + body = { + properties = { + targetResourceId = var.target_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + endpointLocation = var.endpoint_location + } + } + } + bicep_pattern: | + resource tmEndpoint 'Microsoft.Network/trafficManagerProfiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: endpointName + properties: { + targetResourceId: targetResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + endpointLocation: endpointLocation + } + } + prohibitions: + - Do not configure all endpoints with the same priority in Priority routing — creates ambiguous failover + - Do not leave endpoints in Disabled state without documentation +- id: AZ-TM-003 + severity: recommended + description: Enable diagnostic settings for Traffic Manager profile + rationale: Monitor endpoint health probe results and DNS query patterns + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + resource "azapi_resource" "tm_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-traffic-manager" + parent_id = azapi_resource.traffic_manager.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "ProbeHealthStatusEvents" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource tmDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-traffic-manager' + scope: trafficManager + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'ProbeHealthStatusEvents' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit ProbeHealthStatusEvents — they are critical for failover diagnostics +- id: AZ-TM-004 + severity: recommended + description: Use nested profiles for complex routing topologies + rationale: Nested profiles allow combining routing methods (e.g., Performance at top, Weighted at region level) + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/trafficManagerProfiles@2022-04-01 + name: tm-child + description: Child profile + targets: + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + resource "azapi_resource" "tm_nested_endpoint" { + type = "Microsoft.Network/trafficManagerProfiles/nestedEndpoints@2022-04-01" + name = var.nested_endpoint_name + parent_id = azapi_resource.traffic_manager.id + body = { + properties = { + targetResourceId = azapi_resource.child_profile.id + endpointStatus = "Enabled" + minChildEndpoints = 1 + minChildEndpointsIPv4 = 1 + priority = 1 + } + } + } + bicep_pattern: | + resource tmNestedEndpoint 'Microsoft.Network/trafficManagerProfiles/nestedEndpoints@2022-04-01' = { + parent: trafficManager + name: nestedEndpointName + properties: { + targetResourceId: childProfile.id + endpointStatus: 'Enabled' + minChildEndpoints: 1 + minChildEndpointsIPv4: 1 + priority: 1 + } + } + prohibitions: + - Do not set minChildEndpoints to 0 — profile will never fail over +patterns: +- name: Traffic Manager with Performance routing and HTTPS monitoring + description: Multi-region failover with Performance routing and health probes + example: | + # See TM-001 through TM-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not use HTTP health monitoring for production endpoints + instead: Always use HTTPS monitoring with a proper health check path +- description: Do not use Traffic Manager with a single endpoint + instead: Use at least two endpoints in different regions for high availability +references: +- title: Traffic Manager documentation + url: https://learn.microsoft.com/azure/traffic-manager/traffic-manager-overview +- title: Traffic Manager routing methods + url: https://learn.microsoft.com/azure/traffic-manager/traffic-manager-routing-methods diff --git a/azext_prototype/governance/policies/azure/networking/virtual-network.policy.yaml b/azext_prototype/governance/policies/azure/networking/virtual-network.policy.yaml new file mode 100644 index 0000000..103fae8 --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/virtual-network.policy.yaml @@ -0,0 +1,366 @@ +kind: policy +domain: azure-networking +description: Governance policies for Virtual Network +last_updated: '2026-03-27' +rules: +- id: AZ-VNET-001 + severity: required + description: Create Virtual Network with planned address space and purpose-specific subnets + rationale: Address space must be planned to avoid overlap; subnets must be sized for their workload type + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/virtualNetworks + terraform_pattern: | + # VNet declares ONLY addressSpace — subnets are separate child resources + resource "azapi_resource" "virtual_network" { + type = "Microsoft.Network/virtualNetworks@2024-01-01" + name = var.vnet_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + addressSpace = { + addressPrefixes = [var.vnet_address_space] + } + } + } + } + + # Each subnet is a separate child resource to prevent drift + resource "azapi_resource" "subnet_app" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "snet-app" + parent_id = azapi_resource.virtual_network.id + + body = { + properties = { + addressPrefix = var.app_subnet_prefix + delegations = [ + { + name = "delegation-app" + properties = { + serviceName = "Microsoft.Web/serverFarms" + } + } + ] + networkSecurityGroup = { + id = azapi_resource.nsg_app.id + } + } + } + + depends_on = [azapi_resource.nsg_app] + } + + resource "azapi_resource" "subnet_pe" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "snet-pe" + parent_id = azapi_resource.virtual_network.id + + body = { + properties = { + addressPrefix = var.pe_subnet_prefix + networkSecurityGroup = { + id = azapi_resource.nsg_pe.id + } + } + } + + depends_on = [azapi_resource.nsg_pe, azapi_resource.subnet_app] + } + + resource "azapi_resource" "subnet_aca" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "snet-aca" + parent_id = azapi_resource.virtual_network.id + + body = { + properties = { + addressPrefix = var.aca_subnet_prefix + delegations = [ + { + name = "delegation-aca" + properties = { + serviceName = "Microsoft.App/environments" + } + } + ] + networkSecurityGroup = { + id = azapi_resource.nsg_aca.id + } + } + } + + depends_on = [azapi_resource.nsg_aca, azapi_resource.subnet_pe] + } + bicep_pattern: | + // VNet declares ONLY addressSpace — subnets are separate child resources + resource virtualNetwork 'Microsoft.Network/virtualNetworks@2024-01-01' = { + name: vnetName + location: location + properties: { + addressSpace: { + addressPrefixes: [ + vnetAddressSpace + ] + } + } + } + + // Each subnet is a separate child resource to prevent drift + resource subnetApp 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: virtualNetwork + name: 'snet-app' + properties: { + addressPrefix: appSubnetPrefix + delegations: [ + { + name: 'delegation-app' + properties: { + serviceName: 'Microsoft.Web/serverFarms' + } + } + ] + networkSecurityGroup: { + id: nsgApp.id + } + } + } + + resource subnetPe 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: virtualNetwork + name: 'snet-pe' + dependsOn: [subnetApp] + properties: { + addressPrefix: peSubnetPrefix + networkSecurityGroup: { + id: nsgPe.id + } + } + } + + resource subnetAca 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: virtualNetwork + name: 'snet-aca' + dependsOn: [subnetPe] + properties: { + addressPrefix: acaSubnetPrefix + delegations: [ + { + name: 'delegation-aca' + properties: { + serviceName: 'Microsoft.App/environments' + } + } + ] + networkSecurityGroup: { + id: nsgAca.id + } + } + } + prohibitions: + - NEVER define subnets inline in the VNet body -- always create subnets as separate child resources to prevent Terraform/ARM + drift + - NEVER create a subnet without an NSG attached + - NEVER use a /8 or /16 address space for POC -- use /20 or smaller to avoid address space waste + - NEVER overlap subnet address ranges + - NEVER use overlapping address spaces with peered VNets +- id: AZ-VNET-002 + severity: required + description: Create Network Security Groups with explicit rules for every subnet + rationale: NSGs provide network-level access control; every subnet must have an NSG to enforce least-privilege traffic flow + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/virtualNetworks + terraform_pattern: | + resource "azapi_resource" "nsg_app" { + type = "Microsoft.Network/networkSecurityGroups@2024-01-01" + name = "nsg-${var.project_name}-app" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + securityRules = [ + { + name = "AllowHTTPS" + properties = { + priority = 100 + direction = "Inbound" + access = "Allow" + protocol = "Tcp" + sourcePortRange = "*" + destinationPortRange = "443" + sourceAddressPrefix = "*" + destinationAddressPrefix = "*" + } + }, + { + name = "DenyAllInbound" + properties = { + priority = 4096 + direction = "Inbound" + access = "Deny" + protocol = "*" + sourcePortRange = "*" + destinationPortRange = "*" + sourceAddressPrefix = "*" + destinationAddressPrefix = "*" + } + } + ] + } + } + } + + resource "azapi_resource" "nsg_pe" { + type = "Microsoft.Network/networkSecurityGroups@2024-01-01" + name = "nsg-${var.project_name}-pe" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + securityRules = [ + { + name = "DenyAllInbound" + properties = { + priority = 4096 + direction = "Inbound" + access = "Deny" + protocol = "*" + sourcePortRange = "*" + destinationPortRange = "*" + sourceAddressPrefix = "*" + destinationAddressPrefix = "*" + } + } + ] + } + } + } + bicep_pattern: | + resource nsgApp 'Microsoft.Network/networkSecurityGroups@2024-01-01' = { + name: 'nsg-${projectName}-app' + location: location + properties: { + securityRules: [ + { + name: 'AllowHTTPS' + properties: { + priority: 100 + direction: 'Inbound' + access: 'Allow' + protocol: 'Tcp' + sourcePortRange: '*' + destinationPortRange: '443' + sourceAddressPrefix: '*' + destinationAddressPrefix: '*' + } + } + { + name: 'DenyAllInbound' + properties: { + priority: 4096 + direction: 'Inbound' + access: 'Deny' + protocol: '*' + sourcePortRange: '*' + destinationPortRange: '*' + sourceAddressPrefix: '*' + destinationAddressPrefix: '*' + } + } + ] + } + } + + resource nsgPe 'Microsoft.Network/networkSecurityGroups@2024-01-01' = { + name: 'nsg-${projectName}-pe' + location: location + properties: { + securityRules: [ + { + name: 'DenyAllInbound' + properties: { + priority: 4096 + direction: 'Inbound' + access: 'Deny' + protocol: '*' + sourcePortRange: '*' + destinationPortRange: '*' + sourceAddressPrefix: '*' + destinationAddressPrefix: '*' + } + } + ] + } + } +- id: AZ-VNET-003 + severity: required + description: Use proper subnet delegation for Azure services that require it + rationale: Services like App Service, Container Apps, and others require subnet delegation to function correctly + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/virtualNetworks + prohibitions: + - NEVER create a subnet for App Service without Microsoft.Web/serverFarms delegation + - NEVER create a subnet for Container Apps without Microsoft.App/environments delegation + - NEVER delegate a private endpoint subnet — PE subnets must NOT have delegations + - NEVER share a delegated subnet between different service types +- id: AZ-VNET-004 + severity: required + description: Plan subnet sizes according to service requirements + rationale: App Service VNet integration needs /26 minimum; Container Apps needs /23 minimum; PE subnets need /27 minimum + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/virtualNetworks + prohibitions: + - NEVER create an App Service integration subnet smaller than /26 + - NEVER create a Container Apps subnet smaller than /23 + - NEVER create a private endpoint subnet smaller than /27 +- id: AZ-VNET-005 + severity: recommended + description: 'Use standard naming convention for subnets: snet-{purpose}' + rationale: Consistent naming enables automation and reduces configuration errors + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/virtualNetworks +patterns: +- name: VNet with delegated subnets and NSGs + description: Complete VNet deployment with purpose-specific subnets, delegations, and NSGs +anti_patterns: +- description: Do not create subnets without NSGs + instead: Attach an NSG to every subnet +- description: Do not use a single large subnet for all services + instead: Create purpose-specific subnets with appropriate delegations +- description: Do not use /8 or /16 address spaces for POC + instead: Use /20 or /22 for POC; plan for future growth without waste +references: +- title: Virtual network planning + url: https://learn.microsoft.com/azure/virtual-network/virtual-network-vnet-plan-design-arm +- title: Network security groups + url: https://learn.microsoft.com/azure/virtual-network/network-security-groups-overview +- title: Subnet delegation + url: https://learn.microsoft.com/azure/virtual-network/subnet-delegation-overview diff --git a/azext_prototype/governance/policies/azure/networking/vpn-gateway.policy.yaml b/azext_prototype/governance/policies/azure/networking/vpn-gateway.policy.yaml new file mode 100644 index 0000000..4bde8ac --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/vpn-gateway.policy.yaml @@ -0,0 +1,345 @@ +kind: policy +domain: azure-networking +description: Governance policies for Vpn Gateway +last_updated: '2026-03-27' +rules: +- id: AZ-VPN-001 + severity: required + description: Deploy VPN Gateway with VpnGw2AZ or higher SKU for zone redundancy + rationale: AZ SKUs provide availability zone support; VpnGw1 lacks zone redundancy and has limited bandwidth + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/publicIPAddresses@2023-04-01 + name: pip-resource + description: Two Standard SKU static IPs for active-active + - type: Microsoft.Network/virtualNetworks/subnets@2024-01-01 + name: GatewaySubnet + description: GatewaySubnet with /27 or larger + - type: Microsoft.Network/localNetworkGateways@2023-04-01 + name: lgw-onprem + description: On-premises network definition + - type: Microsoft.Network/connections@2023-04-01 + name: s2s-connection + description: Site-to-site connection resource + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-udr + description: Route logs to Log Analytics + targets: + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + resource "azapi_resource" "vpn_gateway" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gateway_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" + tier = "VpnGw2AZ" + } + enableBgp = true + activeActive = true + ipConfigurations = [ + { + name = "vnetGatewayConfig1" + properties = { + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.gateway_subnet_id + } + publicIPAddress = { + id = azapi_resource.vpn_pip_1.id + } + } + }, + { + name = "vnetGatewayConfig2" + properties = { + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.gateway_subnet_id + } + publicIPAddress = { + id = azapi_resource.vpn_pip_2.id + } + } + } + ] + } + } + } + bicep_pattern: | + resource vpnGateway 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGatewayName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' + tier: 'VpnGw2AZ' + } + enableBgp: true + activeActive: true + ipConfigurations: [ + { + name: 'vnetGatewayConfig1' + properties: { + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: gatewaySubnetId + } + publicIPAddress: { + id: vpnPip1.id + } + } + } + { + name: 'vnetGatewayConfig2' + properties: { + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: gatewaySubnetId + } + publicIPAddress: { + id: vpnPip2.id + } + } + } + ] + } + } + prohibitions: + - Do not use Basic SKU — it is legacy and does not support AZ, BGP, or active-active + - Do not use PolicyBased VPN type — RouteBased is required for most scenarios + - Do not deploy single-instance VPN Gateway in production — use active-active +- id: AZ-VPN-002 + severity: required + description: Use IKEv2 with custom IPsec/IKE policy for site-to-site connections + rationale: Default policies use weaker algorithms; custom policies enforce strong encryption + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/virtualNetworkGateways@2023-04-01 + name: vpngw + description: VPN gateway + - type: Microsoft.Network/localNetworkGateways@2023-04-01 + name: lgw-onprem + description: On-premises gateway + targets: + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + resource "azapi_resource" "vpn_connection" { + type = "Microsoft.Network/connections@2024-01-01" + name = var.connection_name + location = var.location + parent_id = var.resource_group_id + body = { + properties = { + connectionType = "IPsec" + virtualNetworkGateway1 = { + id = azapi_resource.vpn_gateway.id + } + localNetworkGateway2 = { + id = azapi_resource.local_gateway.id + } + sharedKey = var.shared_key + enableBgp = true + connectionProtocol = "IKEv2" + usePolicyBasedTrafficSelectors = false + ipsecPolicies = [ + { + saLifeTimeSeconds = 27000 + saDataSizeKilobytes = 102400000 + ipsecEncryption = "AES256" + ipsecIntegrity = "SHA256" + ikeEncryption = "AES256" + ikeIntegrity = "SHA256" + dhGroup = "DHGroup14" + pfsGroup = "PFS2048" + } + ] + } + } + } + bicep_pattern: | + resource vpnConnection 'Microsoft.Network/connections@2024-01-01' = { + name: connectionName + location: location + properties: { + connectionType: 'IPsec' + virtualNetworkGateway1: { + id: vpnGateway.id + } + localNetworkGateway2: { + id: localGateway.id + } + sharedKey: sharedKey + enableBgp: true + connectionProtocol: 'IKEv2' + usePolicyBasedTrafficSelectors: false + ipsecPolicies: [ + { + saLifeTimeSeconds: 27000 + saDataSizeKilobytes: 102400000 + ipsecEncryption: 'AES256' + ipsecIntegrity: 'SHA256' + ikeEncryption: 'AES256' + ikeIntegrity: 'SHA256' + dhGroup: 'DHGroup14' + pfsGroup: 'PFS2048' + } + ] + } + } + prohibitions: + - Do not use IKEv1 — it is deprecated and has known vulnerabilities + - Do not use DES or 3DES encryption — use AES256 + - Do not hardcode sharedKey in templates — use Key Vault references or parameters + - Do not use DHGroup1 or DHGroup2 — use DHGroup14 or higher +- id: AZ-VPN-003 + severity: required + description: Deploy GatewaySubnet with /27 or larger prefix for VPN Gateway + rationale: VPN Gateway requires a dedicated GatewaySubnet; /27 allows for future growth and active-active + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: [] + targets: + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + resource "azapi_resource" "gateway_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "GatewaySubnet" + parent_id = azapi_resource.vnet.id + body = { + properties = { + addressPrefix = var.gateway_subnet_prefix + } + } + } + bicep_pattern: | + resource gatewaySubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + parent: vnet + name: 'GatewaySubnet' + properties: { + addressPrefix: gatewaySubnetPrefix + } + } + prohibitions: + - Do not name the subnet anything other than GatewaySubnet + - Do not use a prefix smaller than /27 + - Do not attach NSG to GatewaySubnet — it is not supported for VPN Gateway + - Do not attach route tables to GatewaySubnet unless specifically required +- id: AZ-VPN-004 + severity: recommended + description: Enable diagnostic settings for VPN Gateway tunnel and route logs + rationale: Tunnel diagnostics are critical for troubleshooting connectivity and monitoring BGP sessions + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace + targets: + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + resource "azapi_resource" "vpn_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-vpn-gateway" + parent_id = azapi_resource.vpn_gateway.id + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + category = "GatewayDiagnosticLog" + enabled = true + }, + { + category = "TunnelDiagnosticLog" + enabled = true + }, + { + category = "RouteDiagnosticLog" + enabled = true + }, + { + category = "IKEDiagnosticLog" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource vpnDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-vpn-gateway' + scope: vpnGateway + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + category: 'GatewayDiagnosticLog' + enabled: true + } + { + category: 'TunnelDiagnosticLog' + enabled: true + } + { + category: 'RouteDiagnosticLog' + enabled: true + } + { + category: 'IKEDiagnosticLog' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + prohibitions: + - Do not omit TunnelDiagnosticLog — it is the primary source for VPN troubleshooting +patterns: +- name: Active-active VPN Gateway with custom IPsec + description: Zone-redundant VPN Gateway with BGP, active-active, and strong IPsec policy + example: | + # See VPN-001 through VPN-004 for complete azapi_resource patterns +anti_patterns: +- description: Do not deploy a single-instance VPN Gateway for production + instead: Use active-active configuration with two public IPs for high availability +- description: Do not store VPN shared keys in plain text in source control + instead: Use Key Vault references or secure parameters for shared keys +references: +- title: VPN Gateway documentation + url: https://learn.microsoft.com/azure/vpn-gateway/vpn-gateway-about-vpngateways +- title: IPsec/IKE policy for VPN + url: https://learn.microsoft.com/azure/vpn-gateway/ipsec-ike-policy-howto diff --git a/azext_prototype/governance/policies/azure/networking/waf-policy.policy.yaml b/azext_prototype/governance/policies/azure/networking/waf-policy.policy.yaml new file mode 100644 index 0000000..5d5592b --- /dev/null +++ b/azext_prototype/governance/policies/azure/networking/waf-policy.policy.yaml @@ -0,0 +1,191 @@ +kind: policy +domain: azure-networking +description: Governance policies for Waf Policy +last_updated: '2026-03-27' +rules: +- id: AZ-WAF-001 + severity: required + description: Deploy WAF policy in Prevention mode with OWASP 3.2 managed rule set and bot protection + rationale: Detection mode only logs attacks; Prevention mode actively blocks them; OWASP 3.2 covers current threat landscape + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-waf + description: Diagnostic settings for WAF logs to monitor blocked requests and rule matches + targets: + - services: + - Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies + terraform_pattern: | + resource "azapi_resource" "waf_policy" { + type = "Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies@2024-01-01" + name = var.waf_policy_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + policySettings = { + state = "Enabled" + mode = "Prevention" + requestBodyCheck = true + maxRequestBodySizeInKb = 128 + fileUploadLimitInMb = 100 + requestBodyEnforcement = true + requestBodyInspectLimitInKB = 128 + } + managedRules = { + managedRuleSets = [ + { + ruleSetType = "OWASP" + ruleSetVersion = "3.2" + ruleGroupOverrides = [] + }, + { + ruleSetType = "Microsoft_BotManagerRuleSet" + ruleSetVersion = "1.0" + ruleGroupOverrides = [] + } + ] + exclusions = [] + } + customRules = [] + } + } + } + bicep_pattern: | + resource wafPolicy 'Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies@2024-01-01' = { + name: wafPolicyName + location: location + properties: { + policySettings: { + state: 'Enabled' + mode: 'Prevention' + requestBodyCheck: true + maxRequestBodySizeInKb: 128 + fileUploadLimitInMb: 100 + requestBodyEnforcement: true + requestBodyInspectLimitInKB: 128 + } + managedRules: { + managedRuleSets: [ + { + ruleSetType: 'OWASP' + ruleSetVersion: '3.2' + ruleGroupOverrides: [] + } + { + ruleSetType: 'Microsoft_BotManagerRuleSet' + ruleSetVersion: '1.0' + ruleGroupOverrides: [] + } + ] + exclusions: [] + } + customRules: [] + } + } + prohibitions: + - Never set WAF mode to Detection in production — always use Prevention + - Never disable requestBodyCheck — it is required for SQL injection and XSS detection + - Never remove OWASP managed rule set — only add exclusions for verified false positives + - Never add broad exclusions (e.g., entire rule groups) without documenting justification + - Never deploy Application Gateway without WAF policy association +- id: AZ-WAF-002 + severity: required + description: Enable request body inspection and set appropriate size limits + rationale: Without body inspection, injection attacks in POST payloads bypass the WAF + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies +- id: AZ-WAF-003 + severity: recommended + description: Add custom rules for geo-filtering and rate limiting before managed rules + rationale: Custom rules execute first and can block traffic by geography or rate before managed rule processing + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies + terraform_pattern: | + # Add to customRules array in WAF policy + # Rate limiting custom rule example: + { + name = "RateLimitRule" + priority = 100 + ruleType = "RateLimitRule" + action = "Block" + rateLimitDuration = "OneMin" + rateLimitThreshold = 100 + groupByUserSession = [] + matchConditions = [ + { + matchVariables = [ + { + variableName = "RemoteAddr" + selector = null + } + ] + operator = "IPMatch" + negationConditon = true + matchValues = [] + transforms = [] + } + ] + } + bicep_pattern: | + // Add to customRules array in WAF policy + { + name: 'RateLimitRule' + priority: 100 + ruleType: 'RateLimitRule' + action: 'Block' + rateLimitDuration: 'OneMin' + rateLimitThreshold: 100 + matchConditions: [ + { + matchVariables: [ + { + variableName: 'RemoteAddr' + } + ] + operator: 'IPMatch' + negationConditon: true + matchValues: [] + } + ] + } +- id: AZ-WAF-004 + severity: recommended + description: Configure WAF exclusions only for verified false positives with documented justification + rationale: Overly broad exclusions weaken WAF protection; each exclusion must be validated + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Network/ApplicationGatewayWebApplicationFirewallPolicies +patterns: +- name: WAF policy with OWASP 3.2 and bot protection + description: Prevention mode WAF with managed rules, bot protection, and rate limiting +anti_patterns: +- description: Do not use Detection mode in production + instead: Set mode to Prevention to actively block attacks +- description: Do not add broad WAF exclusions without justification + instead: Add targeted exclusions for specific rules and request fields with documented false positive evidence +references: +- title: Azure WAF on Application Gateway + url: https://learn.microsoft.com/azure/web-application-firewall/ag/ag-overview +- title: WAF policy configuration + url: https://learn.microsoft.com/azure/web-application-firewall/ag/policy-overview diff --git a/azext_prototype/governance/policies/azure/security/__init__.py b/azext_prototype/governance/policies/azure/security/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/security/defender.policy.yaml b/azext_prototype/governance/policies/azure/security/defender.policy.yaml new file mode 100644 index 0000000..6c74761 --- /dev/null +++ b/azext_prototype/governance/policies/azure/security/defender.policy.yaml @@ -0,0 +1,272 @@ +kind: policy +domain: azure-security +description: Governance policies for Defender +last_updated: '2026-03-27' +rules: +- id: AZ-DEF-001 + severity: required + description: Enable Microsoft Defender for Cloud on all resource types used in the deployment + rationale: Defender provides continuous threat detection, vulnerability assessment, and security recommendations + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Security/pricings + terraform_pattern: | + resource "azapi_resource" "defender_servers" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "VirtualMachines" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + subPlan = "P2" + } + } + } + + resource "azapi_resource" "defender_app_services" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "AppServices" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + + resource "azapi_resource" "defender_storage" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "StorageAccounts" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + subPlan = "DefenderForStorageV2" + } + } + } + + resource "azapi_resource" "defender_sql" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "SqlServers" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + + resource "azapi_resource" "defender_keyvault" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "KeyVaults" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + + resource "azapi_resource" "defender_arm" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "Arm" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + + resource "azapi_resource" "defender_containers" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "Containers" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = "Standard" + } + } + } + bicep_pattern: | + targetScope = 'subscription' + + resource defenderServers 'Microsoft.Security/pricings@2024-01-01' = { + name: 'VirtualMachines' + properties: { + pricingTier: 'Standard' + subPlan: 'P2' + } + } + + resource defenderAppServices 'Microsoft.Security/pricings@2024-01-01' = { + name: 'AppServices' + properties: { + pricingTier: 'Standard' + } + } + + resource defenderStorage 'Microsoft.Security/pricings@2024-01-01' = { + name: 'StorageAccounts' + properties: { + pricingTier: 'Standard' + subPlan: 'DefenderForStorageV2' + } + } + + resource defenderSql 'Microsoft.Security/pricings@2024-01-01' = { + name: 'SqlServers' + properties: { + pricingTier: 'Standard' + } + } + + resource defenderKeyVault 'Microsoft.Security/pricings@2024-01-01' = { + name: 'KeyVaults' + properties: { + pricingTier: 'Standard' + } + } + + resource defenderArm 'Microsoft.Security/pricings@2024-01-01' = { + name: 'Arm' + properties: { + pricingTier: 'Standard' + } + } + + resource defenderContainers 'Microsoft.Security/pricings@2024-01-01' = { + name: 'Containers' + properties: { + pricingTier: 'Standard' + } + } + prohibitions: + - Never set pricingTier to Free for production subscriptions + - Never disable Defender for ARM — it monitors control plane operations + - Never skip Defender for Key Vault when Key Vault is deployed + - Never disable Defender for Storage when storage accounts exist +- id: AZ-DEF-002 + severity: required + description: Enable auto-provisioning of security agents and vulnerability assessment + rationale: Auto-provisioning ensures all new resources are automatically protected + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Security/autoProvisioningSettings + terraform_pattern: | + resource "azapi_resource" "defender_auto_provision" { + type = "Microsoft.Security/autoProvisioningSettings@2017-08-01-preview" + name = "default" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + autoProvision = "On" + } + } + } + bicep_pattern: | + targetScope = 'subscription' + + resource autoProvision 'Microsoft.Security/autoProvisioningSettings@2017-08-01-preview' = { + name: 'default' + properties: { + autoProvision: 'On' + } + } +- id: AZ-DEF-003 + severity: required + description: Configure security contact for alert notifications + rationale: Security alerts must reach the operations team promptly for incident response + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.Security/securityContacts + terraform_pattern: | + resource "azapi_resource" "security_contact" { + type = "Microsoft.Security/securityContacts@2020-01-01-preview" + name = "default" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + emails = var.security_contact_email + notificationsByRole = { + state = "On" + roles = ["Owner", "ServiceAdmin"] + } + alertNotifications = { + state = "On" + minimalSeverity = "Medium" + } + } + } + } + bicep_pattern: | + targetScope = 'subscription' + + resource securityContact 'Microsoft.Security/securityContacts@2020-01-01-preview' = { + name: 'default' + properties: { + emails: securityContactEmail + notificationsByRole: { + state: 'On' + roles: ['Owner', 'ServiceAdmin'] + } + alertNotifications: { + state: 'On' + minimalSeverity: 'Medium' + } + } + } + prohibitions: + - Never disable alert notifications for Owner and ServiceAdmin roles + - Never set minimalSeverity to High — Medium ensures broader coverage +- id: AZ-DEF-004 + severity: recommended + description: Enable continuous export of Defender alerts to Log Analytics + rationale: Continuous export enables SIEM integration, custom alerting, and long-term retention beyond Defender + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + - monitoring-agent + targets: + - services: + - Microsoft.Security/pricings +patterns: +- name: Defender for Cloud with full coverage + description: Enable Defender Standard tier on all resource types with auto-provisioning and alert routing +anti_patterns: +- description: Do not use Free tier Defender in production + instead: Enable Standard tier on all resource types used in the deployment +- description: Do not skip security contact configuration + instead: Configure security contact email with alert notifications enabled +references: +- title: Microsoft Defender for Cloud documentation + url: https://learn.microsoft.com/azure/defender-for-cloud/defender-for-cloud-introduction +- title: Defender for Cloud pricing tiers + url: https://learn.microsoft.com/azure/defender-for-cloud/enhanced-security-features-overview diff --git a/azext_prototype/governance/policies/azure/security/key-vault.policy.yaml b/azext_prototype/governance/policies/azure/security/key-vault.policy.yaml new file mode 100644 index 0000000..f15b5ec --- /dev/null +++ b/azext_prototype/governance/policies/azure/security/key-vault.policy.yaml @@ -0,0 +1,336 @@ +kind: policy +domain: azure-security +description: Governance policies for Key Vault +last_updated: '2026-03-27' +rules: +- id: AZ-KV-001 + severity: required + description: Create Key Vault with RBAC authorization, soft-delete, purge protection, and public access disabled + rationale: RBAC is the recommended authorization model; soft-delete and purge protection prevent accidental permanent deletion; + private access only + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-keyvault + description: Private endpoint for Key Vault — required when publicNetworkAccess is Disabled + terraform_pattern: | + resource "azapi_resource" "kv_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.key_vault_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.key_vault_name}" + properties = { + privateLinkServiceId = azapi_resource.key_vault.id + groupIds = ["vault"] + } + } + ] + } + } + } + bicep_pattern: | + resource kvPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${keyVaultName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${keyVaultName}' + properties: { + privateLinkServiceId: keyVault.id + groupIds: [ + 'vault' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.vaultcore.azure.net + description: Private DNS zone for Key Vault private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "kv_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.vaultcore.azure.net" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "kv_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.kv_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "kv_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.kv_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-vaultcore-azure-net" + properties = { + privateDnsZoneId = azapi_resource.kv_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource kvDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.vaultcore.azure.net' + location: 'global' + } + + resource kvDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: kvDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource kvPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: kvPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-vaultcore-azure-net' + properties: { + privateDnsZoneId: kvDnsZone.id + } + } + ] + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-keyvault + description: Diagnostic settings for Key Vault to Log Analytics — audit trail for secret access and key operations + terraform_pattern: | + resource "azapi_resource" "kv_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.key_vault_name}" + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource kvDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: keyVault + name: 'diag-${keyVaultName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + template_check: + scope: + - key-vault + require_config: + - rbac_authorization + - soft_delete + - purge_protection + error_message: 'Service ''{service_name}'' ({service_type}) missing {config_key}: true' + targets: + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + enableRbacAuthorization = true + enableSoftDelete = true + softDeleteRetentionInDays = 90 + enablePurgeProtection = true + publicNetworkAccess = "Disabled" + networkAcls = { + defaultAction = "Deny" + bypass = "AzureServices" + } + } + } + } + bicep_pattern: | + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + tenantId: tenant().tenantId + sku: { + family: 'A' + name: 'standard' + } + enableRbacAuthorization: true + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + publicNetworkAccess: 'Disabled' + networkAcls: { + defaultAction: 'Deny' + bypass: 'AzureServices' + } + } + } + prohibitions: + - NEVER set enableRbacAuthorization to false — do not use access policies + - NEVER set enableSoftDelete to false + - NEVER set enablePurgeProtection to false + - NEVER set publicNetworkAccess to Enabled + - NEVER use service principal secrets to access Key Vault — use managed identity +- id: AZ-KV-002 + severity: required + description: Assign Key Vault RBAC roles to application identities + rationale: Least-privilege access via built-in roles replaces broad access policies + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Key Vault Secrets User + description: Key Vault Secrets User role (4633458b-17de-408a-b874-0445c86b69e6) for reading secrets + terraform_pattern: | + resource "azapi_resource" "kv_secrets_user_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.kv_secrets_user_role_name + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" + principalId = var.app_identity_principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource kvSecretsUserRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: keyVault + name: kvSecretsUserRoleName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') + principalId: appIdentityPrincipalId + principalType: 'ServicePrincipal' + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Key Vault Crypto User + description: Key Vault Crypto User role (12338af0-0e69-4776-bea7-57ae8d297424) for cryptographic operations — ONLY required + when the architecture uses key encrypt/decrypt/wrap/unwrap operations + terraform_pattern: | + resource "azapi_resource" "kv_crypto_user_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.kv_crypto_user_role_name + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/12338af0-0e69-4776-bea7-57ae8d297424" + principalId = var.app_identity_principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource kvCryptoUserRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: keyVault + name: kvCryptoUserRoleName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '12338af0-0e69-4776-bea7-57ae8d297424') + principalId: appIdentityPrincipalId + principalType: 'ServicePrincipal' + } + } + targets: + - services: + - Microsoft.KeyVault/vaults +patterns: +- name: Key Vault with RBAC and private endpoint + description: Complete Key Vault deployment with RBAC authorization, soft-delete, purge protection, private endpoint, diagnostics, + and role assignments +anti_patterns: +- description: Do not use access policies for authorization + instead: Set enableRbacAuthorization = true and use role assignments +- description: Do not disable soft-delete or purge protection + instead: Keep both enabled with at least 90-day retention +- description: Do not use service principal secrets to access Key Vault + instead: Use managed identity with Key Vault RBAC roles +references: +- title: Key Vault best practices + url: https://learn.microsoft.com/azure/key-vault/general/best-practices +- title: Key Vault RBAC + url: https://learn.microsoft.com/azure/key-vault/general/rbac-guide +- title: Key Vault private endpoints + url: https://learn.microsoft.com/azure/key-vault/general/private-link-service diff --git a/azext_prototype/governance/policies/azure/security/managed-hsm.policy.yaml b/azext_prototype/governance/policies/azure/security/managed-hsm.policy.yaml new file mode 100644 index 0000000..d9a781f --- /dev/null +++ b/azext_prototype/governance/policies/azure/security/managed-hsm.policy.yaml @@ -0,0 +1,238 @@ +kind: policy +domain: azure-security +description: Governance policies for Managed Hsm +last_updated: '2026-03-27' +rules: +- id: AZ-HSM-001 + severity: required + description: Deploy Managed HSM with multiple administrators, RBAC authorization, and no public access + rationale: HSM protects the highest-value cryptographic keys; multiple admins prevent lockout, RBAC enables fine-grained + control + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-hsm + description: Private endpoint for Managed HSM to secure key operations + terraform_pattern: | + resource "azapi_resource" "pe_hsm" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.hsm_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "hsm-connection" + properties = { + privateLinkServiceId = azapi_resource.managed_hsm.id + groupIds = ["managedhsm"] + } + } + ] + } + } + } + bicep_pattern: | + resource peHsm 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${hsmName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'hsm-connection' + properties: { + privateLinkServiceId: managedHsm.id + groupIds: ['managedhsm'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.managedhsm.azure.net + description: Private DNS zone for Managed HSM private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-hsm + description: Diagnostic settings to route HSM audit logs to Log Analytics for compliance + terraform_pattern: | + resource "azapi_resource" "diag_hsm" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.hsm_name}" + parent_id = azapi_resource.managed_hsm.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagHsm 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${hsmName}' + scope: managedHsm + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Managed HSM Crypto User / Officer + description: RBAC local role assignments for key operations — separate Crypto User from Crypto Officer + targets: + - services: + - Microsoft.KeyVault/managedHSMs + terraform_pattern: | + resource "azapi_resource" "managed_hsm" { + type = "Microsoft.KeyVault/managedHSMs@2023-07-01" + name = var.hsm_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_B1" + family = "B" + } + properties = { + tenantId = var.tenant_id + initialAdminObjectIds = var.admin_object_ids # Minimum 3 for quorum + enableSoftDelete = true + softDeleteRetentionInDays = 90 + enablePurgeProtection = true + publicNetworkAccess = "Disabled" + networkAcls = { + bypass = "None" + defaultAction = "Deny" + ipRules = [] + virtualNetworkRules = [] + } + } + } + } + bicep_pattern: | + resource managedHsm 'Microsoft.KeyVault/managedHSMs@2023-07-01' = { + name: hsmName + location: location + sku: { + name: 'Standard_B1' + family: 'B' + } + properties: { + tenantId: tenantId + initialAdminObjectIds: adminObjectIds + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + publicNetworkAccess: 'Disabled' + networkAcls: { + bypass: 'None' + defaultAction: 'Deny' + ipRules: [] + virtualNetworkRules: [] + } + } + } + prohibitions: + - Never deploy with fewer than 3 initial admin object IDs — prevents lockout + - Never disable soft delete or purge protection + - Never set softDeleteRetentionInDays below 90 + - Never set networkAcls bypass to AzureServices unless explicitly required + - Never set publicNetworkAccess to Enabled + - Never combine Crypto Officer and Crypto User roles on the same identity + - Never skip security domain download after initial activation +- id: AZ-HSM-002 + severity: required + description: Enable soft delete with 90-day retention and purge protection + rationale: HSM keys are irrecoverable if permanently deleted; purge protection prevents malicious or accidental permanent + deletion + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.KeyVault/managedHSMs +- id: AZ-HSM-003 + severity: required + description: Download and securely store the security domain immediately after HSM activation + rationale: The security domain is required for disaster recovery; without it, the HSM and its keys are permanently lost + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.KeyVault/managedHSMs +- id: AZ-HSM-004 + severity: required + description: Separate Crypto Officer and Crypto User roles — enforce dual control + rationale: Dual control prevents any single identity from both creating and using keys, reducing insider threat risk + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.KeyVault/managedHSMs +- id: AZ-HSM-005 + severity: recommended + description: Enable diagnostic logging for all key operations to Log Analytics + rationale: HSM audit logs provide compliance evidence and anomaly detection for cryptographic operations + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + - monitoring-agent + targets: + - services: + - Microsoft.KeyVault/managedHSMs +patterns: +- name: Managed HSM with private endpoint and dual control + description: FIPS 140-2 Level 3 HSM with private access, soft delete, purge protection, and role separation +anti_patterns: +- description: Do not deploy HSM with a single administrator + instead: Specify at least 3 initialAdminObjectIds for quorum-based administration +- description: Do not disable soft delete or purge protection + instead: Always enable both with softDeleteRetentionInDays set to 90 +- description: Do not combine Crypto Officer and Crypto User on the same identity + instead: Use separate identities for key management (Officer) and key usage (User) +references: +- title: Azure Managed HSM documentation + url: https://learn.microsoft.com/azure/key-vault/managed-hsm/overview +- title: Managed HSM best practices + url: https://learn.microsoft.com/azure/key-vault/managed-hsm/best-practices diff --git a/azext_prototype/governance/policies/azure/security/sentinel.policy.yaml b/azext_prototype/governance/policies/azure/security/sentinel.policy.yaml new file mode 100644 index 0000000..06ef082 --- /dev/null +++ b/azext_prototype/governance/policies/azure/security/sentinel.policy.yaml @@ -0,0 +1,201 @@ +kind: policy +domain: azure-security +description: Governance policies for Sentinel +last_updated: '2026-03-27' +rules: +- id: AZ-SNTL-001 + severity: required + description: Deploy Microsoft Sentinel on a dedicated Log Analytics workspace with onboarding state enabled + rationale: Sentinel requires an onboarded Log Analytics workspace for security event correlation and threat detection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + companion_resources: + - type: Microsoft.SecurityInsights/dataConnectors@2024-03-01 + name: Azure Activity data connector + description: Data connector for Azure Activity logs — baseline for subscription-level event monitoring + terraform_pattern: | + resource "azapi_resource" "sentinel_azure_activity" { + type = "Microsoft.SecurityInsights/dataConnectors@2024-03-01" + name = var.activity_connector_name + parent_id = azapi_resource.log_analytics.id + + body = { + kind = "AzureActiveDirectory" + properties = { + dataTypes = { + alerts = { + state = "Enabled" + } + } + tenantId = var.tenant_id + } + } + } + bicep_pattern: | + resource sentinelAzureActivity 'Microsoft.SecurityInsights/dataConnectors@2024-03-01' = { + name: activityConnectorName + scope: logAnalytics + kind: 'AzureActiveDirectory' + properties: { + dataTypes: { + alerts: { + state: 'Enabled' + } + } + tenantId: tenantId + } + } + - type: Microsoft.SecurityInsights/alertRules@2024-03-01 + name: Fusion alert rule + description: Built-in Fusion rule for multi-stage attack detection using ML correlation + terraform_pattern: | + resource "azapi_resource" "sentinel_fusion" { + type = "Microsoft.SecurityInsights/alertRules@2024-03-01" + name = var.fusion_rule_name + parent_id = azapi_resource.log_analytics.id + + body = { + kind = "Fusion" + properties = { + enabled = true + alertRuleTemplateName = "f71aba3d-28fb-450b-b192-4e76a83015c8" + } + } + } + bicep_pattern: | + resource sentinelFusion 'Microsoft.SecurityInsights/alertRules@2024-03-01' = { + name: fusionRuleName + scope: logAnalytics + kind: 'Fusion' + properties: { + enabled: true + alertRuleTemplateName: 'f71aba3d-28fb-450b-b192-4e76a83015c8' + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Microsoft Sentinel Responder / Reader + description: RBAC role assignments for SOC analysts and security responders + targets: + - services: + - Microsoft.SecurityInsights/settings + terraform_pattern: | + resource "azapi_resource" "log_analytics" { + type = "Microsoft.OperationalInsights/workspaces@2023-09-01" + name = var.log_analytics_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + name = "PerGB2018" + } + retentionInDays = var.retention_days # Minimum 90 for Sentinel + features = { + enableDataExport = true + } + } + } + } + + resource "azapi_resource" "sentinel" { + type = "Microsoft.SecurityInsights/onboardingStates@2024-03-01" + name = "default" + parent_id = azapi_resource.log_analytics.id + + body = { + properties = { + customerManagedKey = false + } + } + } + bicep_pattern: | + resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = { + name: logAnalyticsName + location: location + properties: { + sku: { + name: 'PerGB2018' + } + retentionInDays: retentionDays + features: { + enableDataExport: true + } + } + } + + resource sentinel 'Microsoft.SecurityInsights/onboardingStates@2024-03-01' = { + name: 'default' + scope: logAnalytics + properties: { + customerManagedKey: false + } + } + prohibitions: + - Never deploy Sentinel on a shared operational Log Analytics workspace — use a dedicated security workspace + - Never set retention below 90 days for Sentinel workspaces + - Never disable the Fusion alert rule — it is the primary ML-based threat detection mechanism + - Never hardcode tenant IDs in data connector configurations + - Never grant Microsoft Sentinel Contributor to analysts — use Responder for incident management +- id: AZ-SNTL-002 + severity: required + description: Enable core data connectors for Azure Activity, Entra ID, and Defender for Cloud + rationale: Data connectors feed Sentinel with security signals; missing connectors create blind spots + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.SecurityInsights/settings +- id: AZ-SNTL-003 + severity: required + description: Enable the Fusion alert rule for ML-based multi-stage attack detection + rationale: Fusion uses ML to correlate low-fidelity signals across data sources into high-confidence incidents + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.SecurityInsights/settings +- id: AZ-SNTL-004 + severity: recommended + description: Configure automation rules for common incident response playbooks + rationale: Automation rules reduce mean time to respond by executing playbooks on incident creation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.SecurityInsights/settings +- id: AZ-SNTL-005 + severity: recommended + description: Set up workspace-level RBAC with Microsoft Sentinel-specific roles + rationale: Sentinel-specific roles (Reader, Responder, Contributor) provide appropriate access levels for SOC tiers + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.SecurityInsights/settings +patterns: +- name: Sentinel with core data connectors and Fusion + description: Dedicated Sentinel workspace with Azure Activity, Entra ID connectors, and Fusion detection +anti_patterns: +- description: Do not deploy Sentinel on a shared operational workspace + instead: Use a dedicated Log Analytics workspace for security monitoring with appropriate retention +- description: Do not disable built-in Fusion detection + instead: Keep Fusion enabled as it provides ML-based multi-stage attack correlation +references: +- title: Microsoft Sentinel documentation + url: https://learn.microsoft.com/azure/sentinel/overview +- title: Sentinel data connectors + url: https://learn.microsoft.com/azure/sentinel/connect-data-sources diff --git a/azext_prototype/governance/policies/azure/sql-database.policy.yaml b/azext_prototype/governance/policies/azure/sql-database.policy.yaml deleted file mode 100644 index a373ec4..0000000 --- a/azext_prototype/governance/policies/azure/sql-database.policy.yaml +++ /dev/null @@ -1,73 +0,0 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: sql-database - category: azure - services: [sql-database] - last_reviewed: "2025-12-01" - -rules: - - id: SQL-001 - severity: required - description: "Use Microsoft Entra authentication, disable SQL auth where possible" - rationale: "Centralised identity management, no password rotation" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [sql-database] - require_config: [entra_auth_only] - error_message: "Service '{service_name}' ({service_type}) missing entra_auth_only: true" - - - id: SQL-002 - severity: required - description: "Enable Transparent Data Encryption (TDE)" - rationale: "Data-at-rest encryption is a baseline security requirement" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [sql-database] - require_config: [tde_enabled] - error_message: "Service '{service_name}' ({service_type}) missing tde_enabled: true" - - - id: SQL-003 - severity: required - description: "Enable Advanced Threat Protection" - rationale: "Detects anomalous database activities" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [sql-database] - require_config: [threat_protection] - error_message: "Service '{service_name}' ({service_type}) missing threat_protection: true" - - - id: SQL-004 - severity: recommended - description: "Use serverless tier for dev/test workloads" - rationale: "Auto-pause reduces costs for intermittent usage" - applies_to: [cloud-architect, cost-analyst, biz-analyst] - - - id: SQL-005 - severity: recommended - description: "Configure geo-replication for production databases" - rationale: "Business continuity and disaster recovery" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - -patterns: - - name: "SQL with Entra auth" - description: "Configure SQL Server with Entra-only authentication" - example: | - resource "azurerm_mssql_server" "main" { - azuread_administrator { - login_username = "sql-admins" - object_id = var.sql_admin_group_id - } - azuread_authentication_only = true - } - -anti_patterns: - - description: "Do not use SQL authentication with username/password" - instead: "Use Microsoft Entra (Azure AD) authentication with managed identity" - - description: "Do not set firewall rule 0.0.0.0-255.255.255.255" - instead: "Use private endpoints or specific IP ranges" - -references: - - title: "SQL Database security best practices" - url: "https://learn.microsoft.com/azure/azure-sql/database/security-best-practice" diff --git a/azext_prototype/governance/policies/azure/storage.policy.yaml b/azext_prototype/governance/policies/azure/storage.policy.yaml deleted file mode 100644 index 6f37d1e..0000000 --- a/azext_prototype/governance/policies/azure/storage.policy.yaml +++ /dev/null @@ -1,91 +0,0 @@ -apiVersion: v1 -kind: policy -metadata: - name: storage - category: azure - services: [storage] - last_reviewed: "2026-02-01" - -rules: - - id: ST-001 - severity: required - description: "Disable shared key access — use Microsoft Entra RBAC for all data-plane operations" - rationale: "Shared keys grant full account access and cannot be scoped" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - template_check: - scope: [storage] - require_config: [shared_key_disabled] - error_message: "Service '{service_name}' ({service_type}) missing shared_key_disabled: true" - - - id: ST-002 - severity: required - description: "Disable public blob access unless explicitly required" - rationale: "Prevents accidental data exposure via anonymous access" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - scope: [storage] - require_config: [public_access_disabled] - error_message: "Service '{service_name}' ({service_type}) missing public_access_disabled: true" - - - id: ST-003 - severity: required - description: "Enforce TLS 1.2 minimum for all storage connections" - rationale: "Older TLS versions have known vulnerabilities" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [storage] - require_config: [min_tls_version] - error_message: "Service '{service_name}' ({service_type}) missing min_tls_version: 'TLS1_2'" - - - id: ST-004 - severity: required - description: "Enable infrastructure encryption (double encryption) for sensitive data" - rationale: "Provides defense-in-depth with separate encryption keys at infra layer" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: ST-005 - severity: recommended - description: "Use private endpoints for storage access from Azure services" - rationale: "Eliminates public internet exposure for the data plane" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - scope: [storage] - require_config: [private_endpoint] - error_message: "Service '{service_name}' ({service_type}) missing private_endpoint: true" - - - id: ST-006 - severity: recommended - description: "Enable blob versioning and soft delete for data protection" - rationale: "Allows recovery from accidental deletion or overwrites" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: ST-007 - severity: recommended - description: "Configure lifecycle management policies for cost optimization" - rationale: "Automatically tier or delete blobs based on age and access patterns" - applies_to: [cloud-architect, terraform-agent, bicep-agent, cost-analyst] - -patterns: - - name: "Storage account with security baseline" - description: "Standard storage deployment with RBAC and private endpoints" - example: | - resource "azurerm_storage_account" "main" { - account_tier = "Standard" - account_replication_type = "LRS" - min_tls_version = "TLS1_2" - shared_access_key_enabled = false - allow_nested_items_to_be_public = false - infrastructure_encryption_enabled = true - } - -anti_patterns: - - description: "Do not use shared key or account key for application access" - instead: "Use managed identity with Storage Blob Data Reader/Contributor role" - - description: "Do not enable public blob access for internal data" - instead: "Disable public access and use private endpoints with managed identity" - -references: - - title: "Storage security recommendations" - url: "https://learn.microsoft.com/azure/storage/blobs/security-recommendations" - - title: "Storage account overview" - url: "https://learn.microsoft.com/azure/storage/common/storage-account-overview" diff --git a/azext_prototype/governance/policies/azure/storage/__init__.py b/azext_prototype/governance/policies/azure/storage/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/storage/storage-account.policy.yaml b/azext_prototype/governance/policies/azure/storage/storage-account.policy.yaml new file mode 100644 index 0000000..02634dc --- /dev/null +++ b/azext_prototype/governance/policies/azure/storage/storage-account.policy.yaml @@ -0,0 +1,496 @@ +kind: policy +domain: azure-storage +description: Governance policies for Storage Account +last_updated: '2026-03-27' +rules: +- id: AZ-ST-001 + severity: required + description: Create Storage Account with shared key disabled, public blob access disabled, TLS 1.2, HTTPS-only, and public + network access disabled + rationale: Shared keys grant full account access and cannot be scoped; public blob access risks data exposure; TLS 1.2 is + the minimum secure transport + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-storage-blob + description: Private endpoint for blob storage — required when publicNetworkAccess is Disabled + terraform_pattern: | + resource "azapi_resource" "storage_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.storage_account_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.storage_account_name}" + properties = { + privateLinkServiceId = azapi_resource.storage_account.id + groupIds = ["blob"] + } + } + ] + } + } + } + bicep_pattern: | + resource storagePrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${storageAccountName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${storageAccountName}' + properties: { + privateLinkServiceId: storageAccount.id + groupIds: [ + 'blob' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.blob.core.windows.net + description: Private DNS zone for blob storage private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "storage_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.blob.core.windows.net" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "storage_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.storage_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "storage_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.storage_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-blob-core-windows-net" + properties = { + privateDnsZoneId = azapi_resource.storage_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource storageDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.blob.core.windows.net' + location: 'global' + } + + resource storageDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: storageDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource storagePeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: storagePrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-blob-core-windows-net' + properties: { + privateDnsZoneId: storageDnsZone.id + } + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Storage Blob Data Contributor + description: Storage Blob Data Contributor role (ba92f5b4-2d11-453d-a403-e96b0029c9fe) for application identity + terraform_pattern: | + resource "azapi_resource" "storage_blob_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.storage_role_assignment_name + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" + principalId = var.app_identity_principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource storageBlobContributorRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: storageAccount + name: storageRoleAssignmentName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe') + principalId: appIdentityPrincipalId + principalType: 'ServicePrincipal' + } + } + template_check: + scope: + - storage + require_config: + - shared_key_disabled + - public_access_disabled + error_message: 'Service ''{service_name}'' ({service_type}) missing {config_key}: true' + targets: + - services: + - Microsoft.Storage/storageAccounts + terraform_pattern: | + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "StorageV2" + sku = { + name = "Standard_LRS" + } + properties = { + allowSharedKeyAccess = false + allowBlobPublicAccess = false + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + publicNetworkAccess = "Disabled" + defaultToOAuthAuthentication = true + networkAcls = { + defaultAction = "Deny" + bypass = "AzureServices" + } + } + } + } + bicep_pattern: | + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + kind: 'StorageV2' + sku: { + name: 'Standard_LRS' + } + properties: { + allowSharedKeyAccess: false + allowBlobPublicAccess: false + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + publicNetworkAccess: 'Disabled' + defaultToOAuthAuthentication: true + networkAcls: { + defaultAction: 'Deny' + bypass: 'AzureServices' + } + } + } + prohibitions: + - NEVER set allowSharedKeyAccess to true — all access must use Entra RBAC + - NEVER set allowBlobPublicAccess to true for internal data + - NEVER set minimumTlsVersion below TLS1_2 + - NEVER set supportsHttpsTrafficOnly to false + - NEVER set publicNetworkAccess to Enabled + - NEVER use account keys or shared access signatures (SAS) for application access — use managed identity with RBAC +- id: AZ-ST-002 + severity: recommended + description: Enable blob versioning and soft delete for data protection + rationale: Allows recovery from accidental deletion or overwrites + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + terraform_pattern: | + resource "azapi_resource" "storage_blob_service" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + isVersioningEnabled = true + deleteRetentionPolicy = { + enabled = true + days = 7 + } + containerDeleteRetentionPolicy = { + enabled = true + days = 7 + } + } + } + } + bicep_pattern: | + resource storageBlobService 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + isVersioningEnabled: true + deleteRetentionPolicy: { + enabled: true + days: 7 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 7 + } + } + } +- id: AZ-ST-003 + severity: recommended + description: Enable diagnostic settings to Log Analytics workspace + rationale: Audit trail for storage access and performance monitoring + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-storage + description: Diagnostic settings for blob storage to Log Analytics + terraform_pattern: | + resource "azapi_resource" "storage_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.storage_account_name}" + parent_id = "${azapi_resource.storage_account.id}/blobServices/default" + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource storageDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: storageBlobService + name: 'diag-${storageAccountName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Storage/storageAccounts +- id: AZ-ST-004 + severity: recommended + description: Configure lifecycle management policies for cost optimization + rationale: Automatically tier or delete blobs based on age and access patterns + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - cost-analyst + targets: + - services: + - Microsoft.Storage/storageAccounts +- id: AZ-ST-005 + severity: recommended + description: Configure zone-redundant or geo-zone-redundant storage replication + rationale: 'WAF Reliability: ZRS replicates across availability zones; GZRS adds cross-region protection for maximum durability + and availability during outages' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + terraform_pattern: | + # In ST-001, change the sku.name to the appropriate redundancy level: + # sku = { + # name = "Standard_ZRS" # or "Standard_GZRS" / "Standard_RAGZRS" + # } + bicep_pattern: | + // In ST-001, change the sku name: + // sku: { + // name: 'Standard_ZRS' // or 'Standard_GZRS' / 'Standard_RAGZRS' + // } +- id: AZ-ST-006 + severity: recommended + description: Enable point-in-time restore for block blob data protection + rationale: 'WAF Reliability: Point-in-time restore protects against accidental blob deletion or corruption, allowing restoration + of block blob data to an earlier state' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + terraform_pattern: | + resource "azapi_resource" "storage_blob_service_restore" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + restorePolicy = { + enabled = true + days = 7 + } + changeFeed = { + enabled = true + } + isVersioningEnabled = true + deleteRetentionPolicy = { + enabled = true + days = 14 + } + } + } + } + bicep_pattern: | + resource storageBlobServiceRestore 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + restorePolicy: { + enabled: true + days: 7 + } + changeFeed: { + enabled: true + } + isVersioningEnabled: true + deleteRetentionPolicy: { + enabled: true + days: 14 + } + } + } +- id: AZ-ST-007 + severity: recommended + description: Apply an Azure Resource Manager lock on the storage account + rationale: 'WAF Security: Locking the account prevents accidental deletion and resulting data loss' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Storage/storageAccounts + terraform_pattern: | + resource "azapi_resource" "storage_lock" { + type = "Microsoft.Authorization/locks@2020-05-01" + name = "lock-${var.storage_account_name}" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + level = "CanNotDelete" + notes = "Prevent accidental deletion of storage account" + } + } + } + bicep_pattern: | + resource storageLock 'Microsoft.Authorization/locks@2020-05-01' = { + scope: storageAccount + name: 'lock-${storageAccountName}' + properties: { + level: 'CanNotDelete' + notes: 'Prevent accidental deletion of storage account' + } + } +- id: AZ-ST-008 + severity: recommended + description: Enable immutability policies for compliance-critical blob data + rationale: 'WAF Security: Immutability policies protect blobs stored for legal, compliance, or other business purposes from + being modified or deleted' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + targets: + - services: + - Microsoft.Storage/storageAccounts +patterns: +- name: Storage account with security baseline + description: Complete storage deployment with RBAC, private endpoint, blob versioning, diagnostics, and role assignment +anti_patterns: +- description: Do not use shared key or account key for application access + instead: Use managed identity with Storage Blob Data Contributor role +- description: Do not enable public blob access for internal data + instead: Disable public access and use private endpoints with managed identity +- description: Do not use SAS tokens for long-lived access + instead: Use managed identity RBAC for application access; use user delegation SAS only for short-lived anonymous access +references: +- title: Storage security recommendations + url: https://learn.microsoft.com/azure/storage/blobs/security-recommendations +- title: Storage account overview + url: https://learn.microsoft.com/azure/storage/common/storage-account-overview +- title: Storage private endpoints + url: https://learn.microsoft.com/azure/storage/common/storage-private-endpoints +- title: 'WAF: Azure Blob Storage service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-blob-storage +- title: Blob data protection overview + url: https://learn.microsoft.com/azure/storage/blobs/data-protection-overview +- title: Immutable storage for blobs + url: https://learn.microsoft.com/azure/storage/blobs/immutable-storage-overview diff --git a/azext_prototype/governance/policies/azure/web/__init__.py b/azext_prototype/governance/policies/azure/web/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/azure/web/api-management.policy.yaml b/azext_prototype/governance/policies/azure/web/api-management.policy.yaml new file mode 100644 index 0000000..7683fb6 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/api-management.policy.yaml @@ -0,0 +1,333 @@ +kind: policy +domain: azure-web +description: Governance policies for Api Management +last_updated: '2026-03-27' +rules: +- id: AZ-APIM-001 + severity: required + description: Deploy API Management with managed identity, VNet integration, and TLS 1.2+ enforcement + rationale: APIM is the gateway for all backend APIs; it must enforce transport security and use managed identity for backend + auth + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-apim + description: Private endpoint for APIM management plane access + terraform_pattern: | + resource "azapi_resource" "pe_apim" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.apim_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.pe_subnet_id + } + privateLinkServiceConnections = [ + { + name = "apim-connection" + properties = { + privateLinkServiceId = azapi_resource.apim.id + groupIds = ["Gateway"] + } + } + ] + } + } + } + bicep_pattern: | + resource peApim 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${apimName}' + location: location + properties: { + subnet: { + id: peSubnetId + } + privateLinkServiceConnections: [ + { + name: 'apim-connection' + properties: { + privateLinkServiceId: apim.id + groupIds: ['Gateway'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.azure-api.net + description: Private DNS zone for APIM gateway private endpoint resolution + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-apim + description: Diagnostic settings for gateway logs, request/response logging to Log Analytics + terraform_pattern: | + resource "azapi_resource" "diag_apim" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.apim_name}" + parent_id = azapi_resource.apim.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagApim 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${apimName}' + scope: apim + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + - type: Microsoft.ApiManagement/service/namedValues@2023-09-01-preview + name: Key Vault named values + description: Named values backed by Key Vault secrets — never store secrets as plain text named values + targets: + - services: + - Microsoft.ApiManagement/service + terraform_pattern: | + resource "azapi_resource" "apim" { + type = "Microsoft.ApiManagement/service@2023-09-01-preview" + name = var.apim_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = var.sku_name # "Developer", "Basic", "Standard", "Premium" + capacity = var.sku_capacity # 1+ + } + properties = { + publisherEmail = var.publisher_email + publisherName = var.publisher_name + virtualNetworkType = "Internal" + virtualNetworkConfiguration = { + subnetResourceId = var.apim_subnet_id + } + customProperties = { + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Ssl30" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30" = "false" + "Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.TripleDes168" = "false" + } + publicNetworkAccess = "Disabled" + disableGateway = false + } + } + } + bicep_pattern: | + resource apim 'Microsoft.ApiManagement/service@2023-09-01-preview' = { + name: apimName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: skuName + capacity: skuCapacity + } + properties: { + publisherEmail: publisherEmail + publisherName: publisherName + virtualNetworkType: 'Internal' + virtualNetworkConfiguration: { + subnetResourceId: apimSubnetId + } + customProperties: { + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Ssl30': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30': 'false' + 'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.TripleDes168': 'false' + } + publicNetworkAccess: 'Disabled' + disableGateway: false + } + } + prohibitions: + - Never hardcode API keys, certificates, or secrets in APIM policies or named values + - Never enable TLS 1.0, TLS 1.1, or SSL 3.0 on gateway or backend + - Never use Triple DES 168 cipher + - Never set virtualNetworkType to None for production — use Internal or External + - Never store plain-text secrets in named values — use Key Vault references + - Never expose management API endpoint publicly without IP restrictions +- id: AZ-APIM-002 + severity: required + description: Use subscription keys or OAuth 2.0 for API authentication — never expose APIs without auth + rationale: Unauthenticated APIs allow unrestricted access and abuse + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-003 + severity: recommended + description: Implement rate limiting and quota policies on all API products + rationale: Rate limiting prevents abuse and ensures fair usage across consumers + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-004 + severity: recommended + description: Use managed identity for backend service authentication + rationale: Eliminates credential management between APIM and backend services + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-005 + severity: recommended + description: Enable zone redundancy for Premium tier APIM instances + rationale: 'WAF Reliability: Zone redundancy ensures resiliency during a datacenter outage within a region; API traffic + continues through remaining units in other zones' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ApiManagement/service + terraform_pattern: | + # Add zones to the APIM resource in APIM-001: + # body = { + # zones = ["1", "2", "3"] + # } + bicep_pattern: | + // Add zones to the APIM resource in APIM-001: + // zones: ['1', '2', '3'] +- id: AZ-APIM-006 + severity: recommended + description: Enable autoscaling or deploy multiple units to handle traffic spikes + rationale: 'WAF Reliability/Performance: Sufficient gateway units guarantee resources to meet demand from API clients, preventing + failures from insufficient capacity' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-007 + severity: recommended + description: Use Defender for APIs for threat detection and API security insights + rationale: 'WAF Security: Defender for APIs provides security insights, recommendations, and threat detection for APIs hosted + in APIM' + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-008 + severity: recommended + description: Implement validate-jwt, validate-content, and validate-headers policies for API security + rationale: 'WAF Security: Delegating security checks to API policies at the gateway reduces nonlegitimate traffic reaching + backend services, protecting integrity and availability' + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-009 + severity: recommended + description: Use built-in cache or external Redis-compatible cache for frequently accessed API responses + rationale: 'WAF Performance/Cost: Caching reduces backend load and response latency; built-in cache avoids the cost of maintaining + an external cache' + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ApiManagement/service +- id: AZ-APIM-010 + severity: recommended + description: Disable the direct management REST API + rationale: 'WAF Security: The direct management API is a legacy control plane access point that increases the attack surface' + applies_to: + - cloud-architect + - security-reviewer + targets: + - services: + - Microsoft.ApiManagement/service +patterns: +- name: APIM with VNet integration and Key Vault + description: Internal APIM deployment with VNet injection, TLS enforcement, and Key Vault-backed secrets +anti_patterns: +- description: Do not store secrets as plain-text named values + instead: Use Key Vault-backed named values with managed identity access +- description: Do not expose APIs without authentication policies + instead: Configure subscription key validation or OAuth 2.0 validation in inbound policies +- description: Do not deploy APIM without VNet integration + instead: Use Internal or External virtualNetworkType with dedicated subnet +references: +- title: API Management security baseline + url: https://learn.microsoft.com/azure/api-management/security-baseline +- title: API Management VNet integration + url: https://learn.microsoft.com/azure/api-management/virtual-network-concepts +- title: 'WAF: API Management service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-api-management +- title: Defender for APIs + url: https://learn.microsoft.com/azure/defender-for-cloud/defender-for-apis-introduction +- title: API Management autoscaling + url: https://learn.microsoft.com/azure/api-management/api-management-howto-autoscale diff --git a/azext_prototype/governance/policies/azure/web/app-service.policy.yaml b/azext_prototype/governance/policies/azure/web/app-service.policy.yaml new file mode 100644 index 0000000..e9625cc --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/app-service.policy.yaml @@ -0,0 +1,498 @@ +kind: policy +domain: azure-web +description: Governance policies for App Service +last_updated: '2026-03-27' +rules: +- id: AZ-AS-001 + severity: required + description: Create App Service Plan with appropriate SKU + rationale: Plan defines compute tier; B1+ required for VNet integration, P1v3+ for production + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + resource "azapi_resource" "app_service_plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + bicep_pattern: | + resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' + tier: 'Basic' + } + properties: { + reserved: true + } + } +- id: AZ-AS-002 + severity: required + description: Create App Service with HTTPS-only, TLS 1.2, managed identity, VNet integration, and public access disabled + rationale: Baseline security configuration prevents cleartext transmission, enables identity-based access, and restricts + network exposure + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-app-service + description: Private endpoint for App Service — required when publicNetworkAccess is Disabled + terraform_pattern: | + resource "azapi_resource" "app_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.app_service_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.app_service_name}" + properties = { + privateLinkServiceId = azapi_resource.app_service.id + groupIds = ["sites"] + } + } + ] + } + } + } + bicep_pattern: | + resource appPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${appServiceName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${appServiceName}' + properties: { + privateLinkServiceId: appService.id + groupIds: [ + 'sites' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azurewebsites.net + description: Private DNS zone for App Service private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "app_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.azurewebsites.net" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "app_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.app_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "app_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.app_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-azurewebsites-net" + properties = { + privateDnsZoneId = azapi_resource.app_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource appDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.azurewebsites.net' + location: 'global' + } + + resource appDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: appDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource appPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: appPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-azurewebsites-net' + properties: { + privateDnsZoneId: appDnsZone.id + } + } + ] + } + } + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-app-service + description: Diagnostic settings for App Service to Log Analytics + terraform_pattern: | + resource "azapi_resource" "app_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.app_service_name}" + parent_id = azapi_resource.app_service.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource appDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: appService + name: 'diag-${appServiceName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + template_check: + scope: + - app-service + require_config: + - https_only + - identity + error_message: 'Service ''{service_name}'' ({service_type}) missing {config_key}: true' + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + resource "azapi_resource" "app_service" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.app_service_name + location = var.location + parent_id = azapi_resource.resource_group.id + + identity { + type = "UserAssigned" + identity_ids = [azapi_resource.user_assigned_identity.id] + } + + body = { + kind = "app,linux" + properties = { + serverFarmId = azapi_resource.app_service_plan.id + httpsOnly = true + publicNetworkAccess = "Disabled" + virtualNetworkSubnetId = var.app_service_subnet_id + siteConfig = { + minTlsVersion = "1.2" + ftpsState = "Disabled" + vnetRouteAllEnabled = true + http20Enabled = true + linuxFxVersion = var.linux_fx_version + } + } + } + } + bicep_pattern: | + resource appService 'Microsoft.Web/sites@2023-12-01' = { + name: appServiceName + location: location + kind: 'app,linux' + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${userAssignedIdentity.id}': {} + } + } + properties: { + serverFarmId: appServicePlan.id + httpsOnly: true + publicNetworkAccess: 'Disabled' + virtualNetworkSubnetId: appServiceSubnetId + siteConfig: { + minTlsVersion: '1.2' + ftpsState: 'Disabled' + vnetRouteAllEnabled: true + http20Enabled: true + linuxFxVersion: linuxFxVersion + } + } + } + prohibitions: + - NEVER set httpsOnly to false + - NEVER set minTlsVersion below 1.2 + - NEVER set ftpsState to AllAllowed — use Disabled + - NEVER set publicNetworkAccess to Enabled + - NEVER store secrets in App Settings as plaintext — use Key Vault references (@Microsoft.KeyVault(SecretUri=...)) +- id: AZ-AS-003 + severity: required + description: Deploy into a VNet-integrated subnet for backend connectivity + rationale: Enables private access to databases, Key Vault, and other PaaS services + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + template_check: + when_services_present: + - app-service + require_service: + - virtual-network + error_message: Template with app-service must include a virtual-network service for VNet integration + targets: + - services: + - Microsoft.Web/sites +- id: AZ-AS-004 + severity: recommended + description: Use deployment slots for zero-downtime deployments in production + rationale: Slot swaps are atomic and support rollback + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites +- id: AZ-AS-005 + severity: recommended + description: Use App Service Authentication (EasyAuth) or custom middleware for user-facing apps + rationale: Built-in auth handles token validation without custom code + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/sites +- id: AZ-AS-006 + severity: recommended + description: Enable health check feature on the App Service + rationale: 'WAF Reliability: Health checks detect problems early and automatically exclude unhealthy instances from serving + requests, improving overall availability' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - monitoring-agent + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # Add to the siteConfig properties in AS-002: + # healthCheckPath = "/health" + bicep_pattern: | + // Add to the siteConfig properties in AS-002: + // healthCheckPath: '/health' +- id: AZ-AS-007 + severity: recommended + description: Disable ARR affinity for stateless applications + rationale: 'WAF Reliability: Disabling ARR affinity distributes incoming requests evenly across all available nodes, preventing + traffic from overwhelming a single node and enabling horizontal scaling' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # Add to the properties block in AS-002: + # clientAffinityEnabled = false + bicep_pattern: | + // Add to the properties block in AS-002: + // clientAffinityEnabled: false +- id: AZ-AS-008 + severity: recommended + description: Enable zone redundancy on the App Service Plan for production workloads + rationale: 'WAF Reliability: Zone redundancy distributes instances across availability zones, maintaining application reliability + if one zone is unavailable' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # Add to the App Service Plan properties in AS-001: + # properties = { + # zoneRedundant = true + # } + bicep_pattern: | + // Add to the App Service Plan properties in AS-001: + // properties: { + // zoneRedundant: true + // } + prohibitions: + - NEVER deploy production workloads on non-zone-redundant plans when the region supports availability zones +- id: AZ-AS-009 + severity: recommended + description: Disable remote debugging and basic authentication + rationale: 'WAF Security: Remote debugging opens inbound ports and basic authentication uses username/password; disabling + both reduces the attack surface' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # Add to the siteConfig properties in AS-002: + # remoteDebuggingEnabled = false + + resource "azapi_resource" "app_basic_auth_ftp" { + type = "Microsoft.Web/sites/basicPublishingCredentialsPolicies@2023-12-01" + name = "ftp" + parent_id = azapi_resource.app_service.id + + body = { + properties = { + allow = false + } + } + } + + resource "azapi_resource" "app_basic_auth_scm" { + type = "Microsoft.Web/sites/basicPublishingCredentialsPolicies@2023-12-01" + name = "scm" + parent_id = azapi_resource.app_service.id + + body = { + properties = { + allow = false + } + } + } + bicep_pattern: | + // Add to the siteConfig properties in AS-002: + // remoteDebuggingEnabled: false + + resource appBasicAuthFtp 'Microsoft.Web/sites/basicPublishingCredentialsPolicies@2023-12-01' = { + parent: appService + name: 'ftp' + properties: { + allow: false + } + } + + resource appBasicAuthScm 'Microsoft.Web/sites/basicPublishingCredentialsPolicies@2023-12-01' = { + parent: appService + name: 'scm' + properties: { + allow: false + } + } + prohibitions: + - NEVER enable remote debugging in production + - NEVER enable basic authentication (FTP or SCM) in production +- id: AZ-AS-010 + severity: recommended + description: Enable auto-heal rules for automatic recovery from unexpected issues + rationale: 'WAF Reliability: Auto-heal triggers healing actions when configurable thresholds are breached (request count, + slow requests, memory limits), enabling automatic proactive maintenance' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites +patterns: +- name: App Service with managed identity and VNet + description: Complete App Service deployment with HTTPS, TLS 1.2, managed identity, VNet integration, private endpoint, + and diagnostics +anti_patterns: +- description: Do not set httpsOnly = false or omit HTTPS enforcement + instead: Always set httpsOnly = true on App Service +- description: Do not store secrets in App Settings as plaintext + instead: Use Key Vault references (@Microsoft.KeyVault(SecretUri=...)) +- description: Do not enable FTP/FTPS access + instead: Set ftpsState to Disabled +references: +- title: App Service security best practices + url: https://learn.microsoft.com/azure/app-service/overview-security +- title: App Service VNet integration + url: https://learn.microsoft.com/azure/app-service/overview-vnet-integration +- title: App Service private endpoints + url: https://learn.microsoft.com/azure/app-service/networking/private-endpoint +- title: 'WAF: App Service Web Apps service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/app-service-web-apps +- title: App Service health check + url: https://learn.microsoft.com/azure/app-service/monitor-instances-health-check +- title: App Service auto-heal + url: https://learn.microsoft.com/azure/app-service/overview-diagnostics#auto-healing diff --git a/azext_prototype/governance/policies/azure/web/container-apps.policy.yaml b/azext_prototype/governance/policies/azure/web/container-apps.policy.yaml new file mode 100644 index 0000000..1a3d522 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/container-apps.policy.yaml @@ -0,0 +1,325 @@ +kind: policy +domain: azure-web +description: Governance policies for Container Apps +last_updated: '2026-03-27' +rules: +- id: AZ-CA-001 + severity: required + description: Create Container Apps Environment with VNet integration and Log Analytics + rationale: Network isolation is mandatory; environment-level logging enables centralized observability + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + when_services_present: + - container-apps + require_service: + - virtual-network + error_message: Template with container-apps must include a virtual-network service for VNet integration + targets: + - services: + - Microsoft.App/managedEnvironments + terraform_pattern: | + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + appLogsConfiguration = { + destination = "log-analytics" + logAnalyticsConfiguration = { + customerId = var.log_analytics_workspace_id + sharedKey = var.log_analytics_shared_key + } + } + zoneRedundant = false + } + } + } + bicep_pattern: | + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + appLogsConfiguration: { + destination: 'log-analytics' + logAnalyticsConfiguration: { + customerId: logAnalyticsWorkspaceId + sharedKey: logAnalyticsSharedKey + } + } + zoneRedundant: false + } + } + prohibitions: + - NEVER use conditional null for vnetConfiguration — azapi v2 serializes null as JSON null which ARM + rejects with 400 Bad Request. Use merge() to omit the property entirely when VNet is disabled. + - NEVER create a Container Apps Environment without linking to a Log Analytics workspace +- id: AZ-CA-002 + severity: required + description: Create Container App with user-assigned managed identity, health probes, and Key Vault secret references + rationale: User-assigned identity enables shared identity across services; probes ensure reliability; Key Vault refs eliminate + secret sprawl + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: AcrPull + description: AcrPull role assignment (7f951dda-4ed3-4680-a7ca-43fe172d538d) granting the managed identity permission + to pull container images from ACR. Without this, the Container App cannot start — the image pull fails silently. + terraform_pattern: | + resource "azapi_resource" "acr_pull_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.acr_pull_role_name + parent_id = var.acr_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" + principalId = var.identity_principal_id + principalType = "ServicePrincipal" + } + } + } + template_check: + scope: + - container-apps + require_config: + - identity + error_message: Service '{service_name}' ({service_type}) missing managed identity configuration + targets: + - services: + - Microsoft.App/containerApps + terraform_pattern: | + resource "azapi_resource" "container_app" { + type = "Microsoft.App/containerApps@2024-03-01" + name = var.container_app_name + location = var.location + parent_id = azapi_resource.resource_group.id + + identity { + type = "UserAssigned" + identity_ids = [azapi_resource.user_assigned_identity.id] + } + + body = { + properties = { + managedEnvironmentId = azapi_resource.container_app_env.id + configuration = { + ingress = { + external = true + targetPort = 8080 + transport = "http" + } + registries = [ + { + server = var.acr_login_server + identity = azapi_resource.user_assigned_identity.id + } + ] + secrets = [ + { + name = "db-connection" + keyVaultUrl = "https://${var.key_vault_name}.vault.azure.net/secrets/db-connection" + identity = azapi_resource.user_assigned_identity.id + } + ] + } + template = { + containers = [ + { + name = var.container_app_name + image = "${var.acr_login_server}/${var.image_name}:${var.image_tag}" + resources = { + cpu = 0.5 + memory = "1Gi" + } + env = [ + { + name = "DB_CONNECTION" + secretRef = "db-connection" + } + ] + probes = [ + { + type = "liveness" + httpGet = { + path = "/healthz" + port = 8080 + } + initialDelaySeconds = 5 + periodSeconds = 10 + }, + { + type = "readiness" + httpGet = { + path = "/ready" + port = 8080 + } + initialDelaySeconds = 3 + periodSeconds = 5 + } + ] + } + ] + scale = { + minReplicas = 0 + maxReplicas = 10 + } + } + } + } + } + bicep_pattern: | + resource containerApp 'Microsoft.App/containerApps@2024-03-01' = { + name: containerAppName + location: location + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${userAssignedIdentity.id}': {} + } + } + properties: { + managedEnvironmentId: containerAppEnv.id + configuration: { + ingress: { + external: true + targetPort: 8080 + transport: 'http' + } + registries: [ + { + server: acrLoginServer + identity: userAssignedIdentity.id + } + ] + secrets: [ + { + name: 'db-connection' + keyVaultUrl: 'https://${keyVaultName}.vault.azure.net/secrets/db-connection' + identity: userAssignedIdentity.id + } + ] + } + template: { + containers: [ + { + name: containerAppName + image: '${acrLoginServer}/${imageName}:${imageTag}' + resources: { + cpu: json('0.5') + memory: '1Gi' + } + env: [ + { + name: 'DB_CONNECTION' + secretRef: 'db-connection' + } + ] + probes: [ + { + type: 'Liveness' + httpGet: { + path: '/healthz' + port: 8080 + } + initialDelaySeconds: 5 + periodSeconds: 10 + } + { + type: 'Readiness' + httpGet: { + path: '/ready' + port: 8080 + } + initialDelaySeconds: 3 + periodSeconds: 5 + } + ] + } + ] + scale: { + minReplicas: 0 + maxReplicas: 10 + } + } + } + } + prohibitions: + - NEVER remove the identity field from KEDA custom scaler blocks — it is a SIBLING of type and metadata, NOT inside + metadata. Without it, KEDA cannot authenticate to Azure services and autoscaling is permanently broken. + - NEVER deploy a Container App that references an ACR registry without an AcrPull role assignment for the managed + identity — the image pull will fail silently at runtime + - NEVER use admin credentials (adminUserEnabled) for ACR access — use managed identity with AcrPull role + - NEVER put secrets directly in environment variables — use Key Vault references via the secrets array with keyVaultUrl + - NEVER deploy Container Apps without health probes — always include liveness and readiness probes + - NEVER use container registry password in registries config — use identity-based auth + - NEVER use identity type 'SystemAssigned' when a user-assigned managed identity stage exists in the plan. Reference the + shared identity from the prior stage via remote state. +- id: AZ-CA-003 + severity: recommended + description: Use consumption plan for dev/test, dedicated for production + rationale: Cost optimization without sacrificing production reliability + applies_to: + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.App/containerApps +- id: AZ-CA-004 + severity: recommended + description: Set min replicas to 0 for non-critical services in dev + rationale: Avoids unnecessary spend during idle periods + applies_to: + - terraform-agent + - bicep-agent + - cost-analyst + targets: + - services: + - Microsoft.App/containerApps +- id: AZ-CA-005 + severity: recommended + description: Enable Container Apps system logs and console logs via environment logging + rationale: Container Apps require explicit log configuration for stdout/stderr capture + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - monitoring-agent + targets: + - services: + - Microsoft.App/managedEnvironments +patterns: +- name: Container App with Key Vault references + description: Use Key Vault references for secrets instead of environment variables +- name: Container App with health probes + description: Always configure liveness and readiness probes for reliability +anti_patterns: +- description: Do not store secrets in environment variables or app settings + instead: Use Key Vault references with managed identity via the secrets array +- description: Do not use admin credentials for container registry + instead: Use managed identity with AcrPull role assignment +- description: Do not deploy Container Apps without VNet integration + instead: Always deploy in a VNet-integrated managed environment +references: +- title: Container Apps landing zone accelerator + url: https://learn.microsoft.com/azure/container-apps/landing-zone-accelerator +- title: Container Apps networking + url: https://learn.microsoft.com/azure/container-apps/networking +- title: Container Apps health probes + url: https://learn.microsoft.com/azure/container-apps/health-probes diff --git a/azext_prototype/governance/policies/azure/web/container-registry.policy.yaml b/azext_prototype/governance/policies/azure/web/container-registry.policy.yaml new file mode 100644 index 0000000..0051652 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/container-registry.policy.yaml @@ -0,0 +1,354 @@ +kind: policy +domain: azure-web +description: Governance policies for Container Registry +last_updated: '2026-03-27' +rules: +- id: AZ-ACR-001 + severity: required + description: Create Container Registry with Premium SKU, admin user disabled, and public access disabled. ALWAYS use Premium + SKU — it is required for private endpoints, retention policies, and geo-replication. NEVER use Basic or Standard SKU. + rationale: Admin credentials are a shared secret that cannot be scoped or audited; public access exposes the registry to + the internet; Premium SKU is required for private endpoint support + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-acr + description: Private endpoint for Container Registry — required when publicNetworkAccess is Disabled (requires Premium + SKU) + terraform_pattern: | + resource "azapi_resource" "acr_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.acr_name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.private_endpoint_subnet_id + } + privateLinkServiceConnections = [ + { + name = "pe-${var.acr_name}" + properties = { + privateLinkServiceId = azapi_resource.container_registry.id + groupIds = ["registry"] + } + } + ] + } + } + } + bicep_pattern: | + resource acrPrivateEndpoint 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${acrName}' + location: location + properties: { + subnet: { + id: privateEndpointSubnetId + } + privateLinkServiceConnections: [ + { + name: 'pe-${acrName}' + properties: { + privateLinkServiceId: containerRegistry.id + groupIds: [ + 'registry' + ] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azurecr.io + description: Private DNS zone for Container Registry private endpoint resolution + terraform_pattern: | + resource "azapi_resource" "acr_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.azurecr.io" + location = "global" + parent_id = azapi_resource.resource_group.id + } + + resource "azapi_resource" "acr_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.acr_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + } + + resource "azapi_resource" "acr_pe_dns_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.acr_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "privatelink-azurecr-io" + properties = { + privateDnsZoneId = azapi_resource.acr_dns_zone.id + } + } + ] + } + } + } + bicep_pattern: | + resource acrDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: 'privatelink.azurecr.io' + location: 'global' + } + + resource acrDnsZoneLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: acrDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + } + + resource acrPeDnsGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: acrPrivateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'privatelink-azurecr-io' + properties: { + privateDnsZoneId: acrDnsZone.id + } + } + ] + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: AcrPull + description: AcrPull role (7f951dda-4ed3-4680-a7ca-43fe172d538d) for pulling images — assign to compute identity + terraform_pattern: | + resource "azapi_resource" "acr_pull_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.acr_pull_role_name + parent_id = azapi_resource.container_registry.id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" + principalId = var.app_identity_principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource acrPullRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: containerRegistry + name: acrPullRoleName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d') + principalId: appIdentityPrincipalId + principalType: 'ServicePrincipal' + } + } + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: AcrPush + description: AcrPush role (8311e382-0749-4cb8-b61a-304f252e45ec) for pushing images — assign to CI/CD identity + terraform_pattern: | + resource "azapi_resource" "acr_push_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.acr_push_role_name + parent_id = azapi_resource.container_registry.id + + body = { + properties = { + roleDefinitionId = "${var.subscription_resource_id}/providers/Microsoft.Authorization/roleDefinitions/8311e382-0749-4cb8-b61a-304f252e45ec" + principalId = var.cicd_identity_principal_id + principalType = "ServicePrincipal" + } + } + } + bicep_pattern: | + resource acrPushRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + scope: containerRegistry + name: acrPushRoleName + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8311e382-0749-4cb8-b61a-304f252e45ec') + principalId: cicdIdentityPrincipalId + principalType: 'ServicePrincipal' + } + } + targets: + - services: + - Microsoft.ContainerRegistry/registries + terraform_pattern: | + resource "azapi_resource" "container_registry" { + type = "Microsoft.ContainerRegistry/registries@2023-11-01-preview" + name = var.acr_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium" + } + properties = { + adminUserEnabled = false + publicNetworkAccess = "Disabled" + networkRuleBypassOptions = "AzureServices" + policies = { + quarantinePolicy = { + status = "disabled" + } + retentionPolicy = { + days = 7 + status = "enabled" + } + } + } + } + } + bicep_pattern: | + resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = { + name: acrName + location: location + sku: { + name: 'Premium' + } + properties: { + adminUserEnabled: false + publicNetworkAccess: 'Disabled' + networkRuleBypassOptions: 'AzureServices' + policies: { + quarantinePolicy: { + status: 'disabled' + } + retentionPolicy: { + days: 7 + status: 'enabled' + } + } + } + } + prohibitions: + - NEVER set adminUserEnabled to true — use managed identity with AcrPull/AcrPush roles + - NEVER set publicNetworkAccess to Enabled + - NEVER use Basic or Standard SKU when private endpoints are required — Premium is required for private endpoints + - NEVER use admin credentials in container runtime configuration — use identity-based registry authentication +- id: AZ-ACR-002 + severity: required + description: Use Premium SKU when private endpoints are required + rationale: Private endpoints are only available on Premium SKU; Basic and Standard do not support private link + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.ContainerRegistry/registries +- id: AZ-ACR-003 + severity: recommended + description: Enable retention policy for untagged manifests + rationale: Prevents unbounded storage growth from untagged images; 7-day retention is a good default + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.ContainerRegistry/registries +- id: AZ-ACR-004 + severity: recommended + description: Enable diagnostic settings to Log Analytics workspace + rationale: Audit trail for image pull/push operations and repository events + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-acr + description: Diagnostic settings for Container Registry to Log Analytics + terraform_pattern: | + resource "azapi_resource" "acr_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.acr_name}" + parent_id = azapi_resource.container_registry.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource acrDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: containerRegistry + name: 'diag-${acrName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.ContainerRegistry/registries +patterns: +- name: Container Registry with private endpoint and RBAC + description: Complete Container Registry deployment with admin disabled, Premium SKU, private endpoint, DNS, and AcrPull/AcrPush + role assignments +anti_patterns: +- description: Do not use admin credentials for container registry access + instead: Use managed identity with AcrPull role for pulling and AcrPush role for pushing +- description: Do not use Basic or Standard SKU when private endpoints are needed + instead: Use Premium SKU which supports private link, retention policies, and geo-replication +- description: Do not store ACR admin password in application configuration + instead: Use identity-based authentication — no credentials needed +references: +- title: Container Registry best practices + url: https://learn.microsoft.com/azure/container-registry/container-registry-best-practices +- title: Container Registry private link + url: https://learn.microsoft.com/azure/container-registry/container-registry-private-link +- title: Container Registry authentication + url: https://learn.microsoft.com/azure/container-registry/container-registry-authentication diff --git a/azext_prototype/governance/policies/azure/web/front-door.policy.yaml b/azext_prototype/governance/policies/azure/web/front-door.policy.yaml new file mode 100644 index 0000000..f1b0389 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/front-door.policy.yaml @@ -0,0 +1,237 @@ +kind: policy +domain: azure-web +description: Governance policies for Front Door +last_updated: '2026-03-27' +rules: +- id: AZ-AFD-001 + severity: required + description: Deploy Azure Front Door Premium with managed identity, WAF policy, and end-to-end TLS + rationale: Front Door is the global entry point; WAF protects against OWASP threats and DDoS; Premium enables private link + origins + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Cdn/profiles/afdEndpoints@2024-02-01 + name: afd-endpoint + description: Front Door endpoint for routing traffic + terraform_pattern: | + resource "azapi_resource" "afd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.endpoint_name + location = "global" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + enabledState = "Enabled" + autoGeneratedDomainNameLabelScope = "TenantReuse" + } + } + } + bicep_pattern: | + resource afdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + name: endpointName + parent: frontDoor + location: 'global' + properties: { + enabledState: 'Enabled' + autoGeneratedDomainNameLabelScope: 'TenantReuse' + } + } + - type: Microsoft.Cdn/profiles/securityPolicies@2024-02-01 + name: security-policy + description: WAF security policy association for the Front Door endpoint + terraform_pattern: | + resource "azapi_resource" "afd_security_policy" { + type = "Microsoft.Cdn/profiles/securityPolicies@2024-02-01" + name = "secpol-${var.front_door_name}" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + parameters = { + type = "WebApplicationFirewall" + wafPolicy = { + id = azapi_resource.waf_policy.id + } + associations = [ + { + domains = [ + { + id = azapi_resource.afd_endpoint.id + } + ] + patternsToMatch = ["/*"] + } + ] + } + } + } + } + bicep_pattern: | + resource afdSecurityPolicy 'Microsoft.Cdn/profiles/securityPolicies@2024-02-01' = { + name: 'secpol-${frontDoorName}' + parent: frontDoor + properties: { + parameters: { + type: 'WebApplicationFirewall' + wafPolicy: { + id: wafPolicy.id + } + associations: [ + { + domains: [ + { + id: afdEndpoint.id + } + ] + patternsToMatch: ['/*'] + } + ] + } + } + } + - type: Microsoft.Cdn/profiles/originGroups@2024-02-01 + name: origin-group + description: Origin group with health probes and load balancing configuration + - type: Microsoft.Cdn/profiles/originGroups/origins@2024-02-01 + name: origin + description: Private link-enabled origin for secure backend connectivity (Premium SKU) + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-afd + description: Diagnostic settings for access logs, WAF logs, and health probe logs + terraform_pattern: | + resource "azapi_resource" "diag_afd" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.front_door_name}" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource diagAfd 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: 'diag-${frontDoorName}' + scope: frontDoor + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Cdn/profiles + terraform_pattern: | + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + location = "global" + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + properties = { + originResponseTimeoutSeconds = 60 + } + } + } + bicep_pattern: | + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Premium_AzureFrontDoor' + } + properties: { + originResponseTimeoutSeconds: 60 + } + } + prohibitions: + - Never deploy Front Door without a WAF policy association + - Never use Standard SKU when private link origins are required — use Premium + - Never allow HTTP-only origins — enforce HTTPS for all origin connections + - Never skip health probes on origin groups + - Never use wildcard domains without explicit WAF rules +- id: AZ-AFD-002 + severity: required + description: Enforce HTTPS-only with TLS 1.2 minimum and redirect HTTP to HTTPS + rationale: HTTP traffic is unencrypted and subject to interception + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +- id: AZ-AFD-003 + severity: required + description: Use private link origins for backend connectivity (Premium SKU) + rationale: Private link origins eliminate public exposure of backend services + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +- id: AZ-AFD-004 + severity: recommended + description: Configure caching rules with appropriate TTLs per content type + rationale: Proper caching reduces origin load, improves latency, and lowers costs + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Cdn/profiles +patterns: +- name: Front Door Premium with WAF and private link + description: Global load balancer with WAF protection, private link origins, and HTTPS enforcement +anti_patterns: +- description: Do not deploy Front Door without WAF policy + instead: Always associate a WAF policy with all Front Door endpoints +- description: Do not use HTTP for origin connections + instead: Set originHostHeader and enforce HTTPS with TLS 1.2 minimum for all origins +references: +- title: Azure Front Door documentation + url: https://learn.microsoft.com/azure/frontdoor/front-door-overview +- title: Front Door WAF policy + url: https://learn.microsoft.com/azure/web-application-firewall/afds/afds-overview diff --git a/azext_prototype/governance/policies/azure/web/functions.policy.yaml b/azext_prototype/governance/policies/azure/web/functions.policy.yaml new file mode 100644 index 0000000..4d7f802 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/functions.policy.yaml @@ -0,0 +1,342 @@ +kind: policy +domain: azure-web +description: Governance policies for Functions +last_updated: '2026-03-27' +rules: +- id: AZ-FN-001 + severity: required + description: Create Azure Functions app with HTTPS-only, TLS 1.2, managed identity, and Key Vault references + rationale: Baseline security configuration prevents cleartext transmission, enables identity-based access, and eliminates + secret sprawl + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + scope: + - functions + require_config: + - https_only + - identity + error_message: 'Service ''{service_name}'' ({service_type}) missing {config_key}: true' + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + resource "azapi_resource" "function_app_plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.function_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + resource "azapi_resource" "function_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.function_app_name + location = var.location + parent_id = azapi_resource.resource_group.id + + identity { + type = "UserAssigned" + identity_ids = [azapi_resource.user_assigned_identity.id] + } + + body = { + kind = "functionapp,linux" + properties = { + serverFarmId = azapi_resource.function_app_plan.id + httpsOnly = true + siteConfig = { + minTlsVersion = "1.2" + ftpsState = "Disabled" + http20Enabled = true + linuxFxVersion = var.linux_fx_version + appSettings = [ + { + name = "AzureWebJobsStorage__accountName" + value = var.storage_account_name + }, + { + name = "FUNCTIONS_EXTENSION_VERSION" + value = "~4" + }, + { + name = "FUNCTIONS_WORKER_RUNTIME" + value = var.functions_worker_runtime + }, + { + name = "APPLICATIONINSIGHTS_CONNECTION_STRING" + value = var.app_insights_connection_string + }, + { + name = "MY_SECRET" + value = "@Microsoft.KeyVault(SecretUri=https://${var.key_vault_name}.vault.azure.net/secrets/my-secret/)" + } + ] + } + } + } + } + bicep_pattern: | + resource functionAppPlan 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + resource functionApp 'Microsoft.Web/sites@2023-12-01' = { + name: functionAppName + location: location + kind: 'functionapp,linux' + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${userAssignedIdentity.id}': {} + } + } + properties: { + serverFarmId: functionAppPlan.id + httpsOnly: true + siteConfig: { + minTlsVersion: '1.2' + ftpsState: 'Disabled' + http20Enabled: true + linuxFxVersion: linuxFxVersion + appSettings: [ + { + name: 'AzureWebJobsStorage__accountName' + value: storageAccountName + } + { + name: 'FUNCTIONS_EXTENSION_VERSION' + value: '~4' + } + { + name: 'FUNCTIONS_WORKER_RUNTIME' + value: functionsWorkerRuntime + } + { + name: 'APPLICATIONINSIGHTS_CONNECTION_STRING' + value: appInsightsConnectionString + } + { + name: 'MY_SECRET' + value: '@Microsoft.KeyVault(SecretUri=https://${keyVaultName}.vault.azure.net/secrets/my-secret/)' + } + ] + } + } + } + prohibitions: + - NEVER set httpsOnly to false + - NEVER set minTlsVersion below 1.2 + - NEVER store secrets directly in appSettings — use Key Vault references (@Microsoft.KeyVault(SecretUri=...)) + - NEVER use AzureWebJobsStorage with a connection string — use identity-based connection with AzureWebJobsStorage__accountName + - NEVER set ftpsState to AllAllowed — use Disabled +- id: AZ-FN-002 + severity: required + description: C# Azure Functions must use the isolated worker model (not in-process) + rationale: In-process model is deprecated; isolated worker provides better performance, dependency isolation, and long-term + support + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + prohibitions: + - NEVER use FUNCTIONS_WORKER_RUNTIME=dotnet (in-process) — use FUNCTIONS_WORKER_RUNTIME=dotnet-isolated + - NEVER reference Microsoft.NET.Sdk.Functions — use Microsoft.Azure.Functions.Worker.Sdk +- id: AZ-FN-003 + severity: recommended + description: Use Consumption plan for event-driven, variable workloads; Premium for VNet or sustained load + rationale: Consumption plan has cold starts but costs nothing at idle; Premium (EP1+) provides VNet integration + applies_to: + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites +- id: AZ-FN-004 + severity: recommended + description: Enable Application Insights for function monitoring and distributed tracing + rationale: Functions are inherently distributed — observability is critical for debugging + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - monitoring-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/sites +- id: AZ-FN-005 + severity: recommended + description: Use durable functions or Service Bus for long-running orchestrations + rationale: Regular functions have a 5-10 minute timeout; durable functions handle complex workflows + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/sites +- id: AZ-FN-006 + severity: recommended + description: Use Premium plan (EP1+) or Flex Consumption when VNet integration is required + rationale: 'WAF Security: Consumption plan does not support VNet integration or private endpoints; Premium/Flex Consumption + provides private networking and prewarmed instances to minimize cold starts' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + prohibitions: + - NEVER use Consumption plan when VNet integration or private endpoints are required +- id: AZ-FN-007 + severity: recommended + description: Enable availability zone support for critical function apps + rationale: 'WAF Reliability: Zone-redundant deployment provides protection against datacenter-level failures through automatic + failover across availability zones' + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # For zone-redundant App Service Plan, set zoneRedundant in AS-001: + # properties = { + # zoneRedundant = true + # } + # Note: Requires Premium v3 plan or Flex Consumption plan + bicep_pattern: | + // For zone-redundant App Service Plan, set zoneRedundant in AS-001: + // properties: { + // zoneRedundant: true + // } + // Note: Requires Premium v3 plan or Flex Consumption plan +- id: AZ-FN-008 + severity: recommended + description: Configure automatic retries for transient errors on function triggers + rationale: 'WAF Reliability: Automatic retries reduce the likelihood of data loss or interruption from transient failures, + improving reliability without custom code' + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/sites +- id: AZ-FN-009 + severity: recommended + description: Enable diagnostic settings to Log Analytics workspace + rationale: Captures function execution logs, errors, and performance metrics + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-function-app + description: Diagnostic settings for Function App to Log Analytics + terraform_pattern: | + resource "azapi_resource" "function_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.function_app_name}" + parent_id = azapi_resource.function_app.id + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } + } + bicep_pattern: | + resource functionDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + scope: functionApp + name: 'diag-${functionAppName}' + properties: { + workspaceId: logAnalyticsWorkspaceId + logs: [ + { + categoryGroup: 'allLogs' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } + } + targets: + - services: + - Microsoft.Web/sites +patterns: +- name: Function App with managed identity and Key Vault references + description: Standard Function App deployment with identity-based storage, Key Vault secret references, and monitoring +anti_patterns: +- description: Do not store connection strings in Function App Settings as plaintext + instead: 'Use Key Vault references: @Microsoft.KeyVault(SecretUri=...)' +- description: Do not use Consumption plan when VNet integration is required + instead: Use Premium plan (EP1+) or App Service plan for VNet-integrated functions +- description: Do not use in-process model for C# functions + instead: Use isolated worker model with Microsoft.Azure.Functions.Worker.Sdk +references: +- title: Azure Functions security + url: https://learn.microsoft.com/azure/azure-functions/security-concepts +- title: Functions networking options + url: https://learn.microsoft.com/azure/azure-functions/functions-networking-options +- title: Functions isolated worker model + url: https://learn.microsoft.com/azure/azure-functions/dotnet-isolated-process-guide +- title: 'WAF: Azure Functions service guide' + url: https://learn.microsoft.com/azure/well-architected/service-guides/azure-functions +- title: Functions error handling and retries + url: https://learn.microsoft.com/azure/azure-functions/functions-bindings-error-pages +- title: Functions reliability + url: https://learn.microsoft.com/azure/reliability/reliability-functions diff --git a/azext_prototype/governance/policies/azure/web/static-web-apps.policy.yaml b/azext_prototype/governance/policies/azure/web/static-web-apps.policy.yaml new file mode 100644 index 0000000..adb9061 --- /dev/null +++ b/azext_prototype/governance/policies/azure/web/static-web-apps.policy.yaml @@ -0,0 +1,167 @@ +kind: policy +domain: azure-web +description: Governance policies for Static Web Apps +last_updated: '2026-03-27' +rules: +- id: AZ-SWA-001 + severity: required + description: Deploy Azure Static Web Apps with Standard SKU, managed identity, and enterprise-grade auth + rationale: Standard SKU enables custom auth, private endpoints, and enterprise features; managed identity secures backend + API connections + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Web/staticSites/config@2023-12-01 + name: appsettings + description: Application settings for backend API configuration — never embed secrets directly + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-swa + description: Private endpoint for Static Web App (Standard SKU only) + terraform_pattern: | + resource "azapi_resource" "pe_swa" { + type = "Microsoft.Network/privateEndpoints@2024-01-01" + name = "pe-${var.swa_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "swa-connection" + properties = { + privateLinkServiceId = azapi_resource.static_web_app.id + groupIds = ["staticSites"] + } + } + ] + } + } + } + bicep_pattern: | + resource peSwa 'Microsoft.Network/privateEndpoints@2024-01-01' = { + name: 'pe-${swaName}' + location: location + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'swa-connection' + properties: { + privateLinkServiceId: staticWebApp.id + groupIds: ['staticSites'] + } + } + ] + } + } + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.azurestaticapps.net + description: Private DNS zone for Static Web App private endpoint resolution + - type: Microsoft.Web/staticSites/linkedBackends@2023-12-01 + name: linked-backend + description: Linked backend API (e.g., Container Apps, Functions) for managed API routing + targets: + - services: + - Microsoft.Web/staticSites + terraform_pattern: | + resource "azapi_resource" "static_web_app" { + type = "Microsoft.Web/staticSites@2023-12-01" + name = var.swa_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + tier = "Standard" + } + properties = { + stagingEnvironmentPolicy = "Enabled" + allowConfigFileUpdates = true + enterpriseGradeCdnStatus = "Enabled" + } + } + } + bicep_pattern: | + resource staticWebApp 'Microsoft.Web/staticSites@2023-12-01' = { + name: swaName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + tier: 'Standard' + } + properties: { + stagingEnvironmentPolicy: 'Enabled' + allowConfigFileUpdates: true + enterpriseGradeCdnStatus: 'Enabled' + } + } + prohibitions: + - Never hardcode API keys or connection strings in staticwebapp.config.json + - Never use Free SKU in production — it lacks private endpoints, custom auth, and SLA + - Never embed secrets in application settings without Key Vault references + - Never disable stagingEnvironmentPolicy — staging environments enable safe preview deployments +- id: AZ-SWA-002 + severity: required + description: Configure custom authentication with identity providers in staticwebapp.config.json + rationale: Default GitHub auth is insufficient for enterprise; custom auth enables Entra ID and other IdPs + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/staticSites +- id: AZ-SWA-003 + severity: recommended + description: Enable enterprise-grade CDN for global content distribution + rationale: Enterprise CDN provides edge caching, WAF integration, and custom domains with managed certificates + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Web/staticSites +- id: AZ-SWA-004 + severity: recommended + description: Configure custom domain with managed SSL certificate + rationale: Managed certificates auto-renew and eliminate manual certificate management + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Web/staticSites +patterns: +- name: Static Web App with linked backend and custom auth + description: Standard SWA with managed identity, linked backend API, and Entra ID authentication +anti_patterns: +- description: Do not use Free tier for production workloads + instead: Use Standard SKU which provides SLA, private endpoints, and enterprise features +- description: Do not rely on default GitHub auth for enterprise applications + instead: Configure custom authentication with Microsoft Entra ID in staticwebapp.config.json +references: +- title: Azure Static Web Apps documentation + url: https://learn.microsoft.com/azure/static-web-apps/overview +- title: Static Web Apps authentication + url: https://learn.microsoft.com/azure/static-web-apps/authentication-authorization diff --git a/azext_prototype/governance/policies/cost/__init__.py b/azext_prototype/governance/policies/cost/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/cost/reserved-instances.policy.yaml b/azext_prototype/governance/policies/cost/reserved-instances.policy.yaml new file mode 100644 index 0000000..4ff264f --- /dev/null +++ b/azext_prototype/governance/policies/cost/reserved-instances.policy.yaml @@ -0,0 +1,103 @@ +kind: policy +domain: cost +description: Governance policies for Reserved Instances +last_updated: '2026-03-27' +rules: +- id: WAF-COST-RI-001 + severity: recommended + description: Recommend Azure Reserved VM Instances for production workloads with stable, predictable compute usage over + 12+ months + rationale: 1-year reservations save 30-40% over pay-as-you-go; 3-year reservations save 55-65%. Only applicable to stable + production workloads + applies_to: + - cost-analyst + - cloud-architect + - project-manager + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers +- id: WAF-COST-RI-002 + severity: recommended + description: Recommend Azure Savings Plans for compute when workloads may change VM size, region, or service type + rationale: Savings Plans provide 15-25% savings with flexibility to change compute type, unlike reservations which are locked + to a specific VM size and region + applies_to: + - cost-analyst + - cloud-architect + - project-manager + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers +- id: WAF-COST-RI-003 + severity: recommended + description: Recommend Cosmos DB reserved capacity for production workloads with predictable RU/s consumption + rationale: Cosmos DB 1-year reserved capacity saves ~20% on provisioned throughput; 3-year saves ~30%. Only for provisioned + (not serverless) accounts + applies_to: + - cost-analyst + - cloud-architect + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers +- id: WAF-COST-RI-004 + severity: recommended + description: Recommend SQL Database reserved capacity for production vCore databases with stable utilization + rationale: SQL reserved capacity saves ~30-40% on provisioned vCore compute (not serverless). Only for databases with consistent + CPU usage + applies_to: + - cost-analyst + - cloud-architect + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers +patterns: +- name: Reservation strategy for production workloads + description: After 1-2 months of production data, analyze Azure Advisor recommendations and purchase 1-year reservations + for stable baseline compute. Use savings plans for flexible workloads +- name: Tag-based reservation tracking + description: Tag reservation-eligible resources with ReservationEligible, ReservationTerm, and service-specific metadata + for cost tracking +anti_patterns: +- description: Do not purchase reservations before production workloads are stable + instead: Wait 1-2 months for usage data; use Azure Advisor reservation recommendations +- description: Do not purchase 3-year reservations for new workloads + instead: Start with 1-year reservations; upgrade to 3-year after confirming workload stability +- description: Do not reserve compute for dev/POC environments + instead: Use pay-as-you-go, serverless, burstable, and spot instances for dev/POC +- description: Do not reserve more capacity than your measured baseline + instead: Reserve the stable baseline; let autoscale/pay-as-you-go handle spikes +references: +- title: Azure Reserved VM Instances + url: https://learn.microsoft.com/azure/cost-management-billing/reservations/save-compute-costs-reservations +- title: Azure Savings Plans + url: https://learn.microsoft.com/azure/cost-management-billing/savings-plan/savings-plan-compute-overview +- title: Cosmos DB reserved capacity + url: https://learn.microsoft.com/azure/cosmos-db/reserved-capacity +- title: SQL Database reserved capacity + url: https://learn.microsoft.com/azure/azure-sql/database/reserved-capacity-overview +- title: Azure Advisor cost recommendations + url: https://learn.microsoft.com/azure/advisor/advisor-cost-recommendations diff --git a/azext_prototype/governance/policies/cost/resource-lifecycle.policy.yaml b/azext_prototype/governance/policies/cost/resource-lifecycle.policy.yaml new file mode 100644 index 0000000..422221b --- /dev/null +++ b/azext_prototype/governance/policies/cost/resource-lifecycle.policy.yaml @@ -0,0 +1,1520 @@ +kind: policy +domain: cost +description: Governance policies for Resource Lifecycle +last_updated: '2026-03-27' +rules: +- id: WAF-COST-LIFE-001 + severity: required + description: Configure auto-shutdown schedules for dev/POC VMs — shut down at 7 PM, no auto-start + rationale: Dev VMs running 24/7 cost 3x more than VMs with 10-hour daily usage; auto-shutdown eliminates forgotten instances + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.DevTestLab/schedules + - Microsoft.OperationalInsights/workspaces + - Microsoft.KeyVault/vaults + - Microsoft.RecoveryServices/vaults + - Microsoft.Resources/resourceGroups +- id: WAF-COST-LIFE-002 + severity: required + description: Configure storage lifecycle management policies — move to Cool after 30 days, Archive after 90 days, delete + after 365 days + rationale: Storage lifecycle policies automatically tier data by age; Cool tier is 50% cheaper than Hot, Archive is 90% + cheaper + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Storage/storageAccounts + - Microsoft.OperationalInsights/workspaces + - Microsoft.KeyVault/vaults + - Microsoft.RecoveryServices/vaults + - Microsoft.Resources/resourceGroups +- id: WAF-COST-LIFE-003 + severity: required + description: Set appropriate Log Analytics retention — 30 days for dev/POC, 90 days for production, with archive tier for + compliance + rationale: Log Analytics charges per GB ingested and per day retained beyond 31 days; reducing retention from 90 to 30 days + saves ~65% + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + - monitoring-agent + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.OperationalInsights/workspaces + - Microsoft.KeyVault/vaults + - Microsoft.RecoveryServices/vaults + - Microsoft.Resources/resourceGroups +- id: WAF-COST-LIFE-004 + severity: required + description: Configure appropriate soft-delete retention periods — shorter for dev/POC, longer for production + rationale: Soft-delete protects against accidental deletion but costs storage; longer retention in dev wastes budget + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.KeyVault/vaults + - Microsoft.OperationalInsights/workspaces + - Microsoft.RecoveryServices/vaults + - Microsoft.Resources/resourceGroups +- id: WAF-COST-LIFE-005 + severity: required + description: Apply mandatory cost tracking tags to all resources — Environment, CostCenter, Owner, Project + rationale: Tags enable cost allocation, showback/chargeback, and automated cleanup of orphaned resources + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + - project-manager + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability + - services: + - Microsoft.Resources/resourceGroups + - Microsoft.Web/serverfarms + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability + - services: + - Microsoft.OperationalInsights/workspaces + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability + - services: + - Microsoft.Resources/resourceGroups + terraform_pattern: | + # === Mandatory Tags (apply to all resources) === + locals { + mandatory_tags = { + Environment = var.environment # "dev", "staging", "prod" + CostCenter = var.cost_center # Cost center code for chargeback + Owner = var.owner_email # Owner email for contact + Project = var.project_name # Project name for grouping + ManagedBy = "terraform" # Automation tool + CreatedDate = formatdate("YYYY-MM-DD", timestamp()) + } + } + + # === Resource Group with tags === + resource "azapi_resource" "resource_group" { + type = "Microsoft.Resources/resourceGroups@2024-03-01" + name = var.resource_group_name + location = var.location + parent_id = "/subscriptions/${var.subscription_id}" + + tags = local.mandatory_tags + + body = {} + } + + # === Tag inheritance: all child resources === + # Apply local.mandatory_tags to every azapi_resource via top-level tags argument + resource "azapi_resource" "example_resource" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.resource_name + location = var.location + parent_id = azapi_resource.resource_group.id + + tags = local.mandatory_tags + + body = {} + } + bicep_pattern: | + // === Mandatory Tags (apply to all resources) === + @description('Environment tier: dev, staging, prod') + param environment string + + @description('Cost center code for chargeback') + param costCenter string + + @description('Owner email for contact') + param ownerEmail string + + @description('Project name for grouping') + param projectName string + + var mandatoryTags = { + Environment: environment + CostCenter: costCenter + Owner: ownerEmail + Project: projectName + ManagedBy: 'bicep' + CreatedDate: utcNow('yyyy-MM-dd') + } + + // === Apply tags to every resource === + resource exampleResource 'Microsoft.Web/serverfarms@2023-12-01' = { + name: resourceName + location: location + tags: mandatoryTags + // ... resource properties + } + prohibitions: + - NEVER deploy resources without at minimum Environment, CostCenter, Owner, and Project tags + - NEVER use free-form tag values for Environment — restrict to 'dev', 'staging', 'prod' + - NEVER omit the ManagedBy tag — it distinguishes IaC-managed from manually-created resources + - NEVER hardcode tag values — always use variables/parameters for reusability +- id: WAF-COST-LIFE-006 + severity: required + description: Configure Azure budget alerts with action groups — monthly budget with 50%, 80%, 100%, and 120% thresholds + rationale: Budget alerts provide early warning before costs exceed expectations; without them, overspend is only discovered + on invoices + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + companion_resources: + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ag-ops + description: Action group for budget alert notifications — required for budget alerts to trigger email/webhook notifications + targets: + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation + - services: + - Microsoft.Consumption/budgets + - Microsoft.Insights/actionGroups + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation + - services: + - Microsoft.OperationalInsights/workspaces + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation + - services: + - Microsoft.Resources/resourceGroups + terraform_pattern: | + # === Budget with Alert Thresholds === + resource "azapi_resource" "budget" { + type = "Microsoft.Consumption/budgets@2023-11-01" + name = "budget-${var.project_name}" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + category = "Cost" + amount = var.monthly_budget # e.g., 500 for $500/month + timeGrain = "Monthly" + timePeriod = { + startDate = var.budget_start_date # e.g., "2026-04-01T00:00:00Z" + } + filter = { + tags = { + name = "Project" + values = [var.project_name] + } + } + notifications = { + "50-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 50 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "80-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 80 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "100-percent" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 100 + thresholdType = "Actual" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + "120-percent-forecast" = { + enabled = true + operator = "GreaterThanOrEqualTo" + threshold = 120 + thresholdType = "Forecasted" + contactEmails = var.budget_alert_emails + contactGroups = [azapi_resource.budget_action_group.id] + } + } + } + } + } + + # === Action Group for Budget Alerts === + resource "azapi_resource" "budget_action_group" { + type = "Microsoft.Insights/actionGroups@2023-01-01" + name = "ag-budget-${var.project_name}" + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + groupShortName = "budget" + enabled = true + emailReceivers = [ + { + name = "owner" + emailAddress = var.owner_email + useCommonAlertSchema = true + } + ] + } + } + } + bicep_pattern: | + // === Budget with Alert Thresholds === + resource budget 'Microsoft.Consumption/budgets@2023-11-01' = { + name: 'budget-${projectName}' + properties: { + category: 'Cost' + amount: monthlyBudget + timeGrain: 'Monthly' + timePeriod: { + startDate: budgetStartDate + } + filter: { + tags: { + name: 'Project' + values: [projectName] + } + } + notifications: { + '50-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 50 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '80-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 80 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '100-percent': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 100 + thresholdType: 'Actual' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + '120-percent-forecast': { + enabled: true + operator: 'GreaterThanOrEqualTo' + threshold: 120 + thresholdType: 'Forecasted' + contactEmails: budgetAlertEmails + contactGroups: [budgetActionGroup.id] + } + } + } + } + + // === Action Group for Budget Alerts === + resource budgetActionGroup 'Microsoft.Insights/actionGroups@2023-01-01' = { + name: 'ag-budget-${projectName}' + location: 'global' + properties: { + groupShortName: 'budget' + enabled: true + emailReceivers: [ + { + name: 'owner' + emailAddress: ownerEmail + useCommonAlertSchema: true + } + ] + } + } + prohibitions: + - NEVER deploy a project without a budget resource and alert thresholds + - NEVER skip the 80% and 100% actual-spend thresholds — they are the primary early warnings + - NEVER skip the forecasted threshold — it provides advance warning before actual spend occurs + - NEVER set budget amount without consulting cost-analyst for estimation + - NEVER use only contactEmails without an action group — action groups support webhooks, Logic Apps, and runbook automation +patterns: +- name: Cost-optimized resource lifecycle + description: Combine auto-shutdown, lifecycle policies, retention limits, mandatory tags, and budget alerts for comprehensive + cost governance +anti_patterns: +- description: Do not deploy resources without cost tracking tags + instead: Apply Environment, CostCenter, Owner, and Project tags to every resource +- description: Do not set unlimited log retention for dev/POC + instead: Use 30 days for dev/POC; use 90 days with archive tier for production +- description: Do not forget to configure budget alerts + instead: Create a monthly budget with 50%, 80%, 100% actual and 120% forecasted thresholds +- description: Do not leave dev VMs running 24/7 + instead: Configure auto-shutdown at 7 PM with 30-minute notification +references: +- title: Azure Cost Management best practices + url: https://learn.microsoft.com/azure/cost-management-billing/costs/cost-mgt-best-practices +- title: Storage lifecycle management + url: https://learn.microsoft.com/azure/storage/blobs/lifecycle-management-overview +- title: Log Analytics pricing + url: https://learn.microsoft.com/azure/azure-monitor/logs/cost-logs +- title: Azure budgets + url: https://learn.microsoft.com/azure/cost-management-billing/costs/tutorial-acm-create-budgets +- title: Azure tagging strategy + url: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-tagging diff --git a/azext_prototype/governance/policies/cost/scaling.policy.yaml b/azext_prototype/governance/policies/cost/scaling.policy.yaml new file mode 100644 index 0000000..6e935db --- /dev/null +++ b/azext_prototype/governance/policies/cost/scaling.policy.yaml @@ -0,0 +1,123 @@ +kind: policy +domain: cost +description: Governance policies for Scaling +last_updated: '2026-03-27' +rules: +- id: WAF-COST-SCALE-001 + severity: required + description: Configure App Service autoscale with CPU-based rules — scale out at >70%, scale in at <30%, with cooldown periods + rationale: Autoscale prevents both over-provisioning (cost waste) and under-provisioning (performance degradation). Cooldown + prevents flapping + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.ContainerService/managedClusters +- id: WAF-COST-SCALE-002 + severity: required + description: Configure Container Apps scaling rules with appropriate min/max replicas and HTTP/custom scaling triggers + rationale: Container Apps scaling is per-app; proper configuration prevents idle costs in dev and ensures availability in + production + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.ContainerService/managedClusters +- id: WAF-COST-SCALE-003 + severity: required + description: Configure VMSS autoscale profiles with CPU-based rules and scheduled profiles for predictable workloads + rationale: VMSS without autoscale runs at fixed capacity; autoscale adapts to demand and reduces off-hours costs + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.ContainerService/managedClusters +- id: WAF-COST-SCALE-004 + severity: required + description: Configure database autoscale — Cosmos DB autoscale maxThroughput for production, SQL elastic pools for multi-database + workloads + rationale: Database scaling directly impacts both cost and performance; autoscale prevents over-provisioning while handling + spikes + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.ContainerService/managedClusters +- id: WAF-COST-SCALE-005 + severity: required + description: Configure AKS cluster autoscaler with appropriate node pool settings — spot nodes for dev, on-demand for production + rationale: AKS cluster autoscaler adjusts node count automatically; spot VMs provide up to 90% savings for interruptible + workloads + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.ContainerService/managedClusters +patterns: +- name: Environment-aware autoscale configuration + description: Dev/POC uses aggressive scale-down with low maximums; production uses higher minimums with zone-redundant capacity +- name: Spot VM cost optimization + description: Use spot VMs for interruptible workloads in dev/POC to achieve up to 90% cost savings +anti_patterns: +- description: Do not deploy compute resources with fixed instance counts + instead: Configure autoscale with appropriate min/max and metrics-based scaling rules +- description: Do not use the same scale configuration for dev and production + instead: Use lower minimums, lower maximums, and scale-to-zero where possible in dev +- description: Do not scale on a single metric + instead: Use CPU as the primary trigger; add memory, queue depth, or HTTP connections as secondary triggers +references: +- title: Azure Autoscale overview + url: https://learn.microsoft.com/azure/azure-monitor/autoscale/autoscale-overview +- title: Container Apps scaling + url: https://learn.microsoft.com/azure/container-apps/scale-app +- title: AKS cluster autoscaler + url: https://learn.microsoft.com/azure/aks/cluster-autoscaler +- title: Cosmos DB autoscale throughput + url: https://learn.microsoft.com/azure/cosmos-db/provision-throughput-autoscale +- title: SQL elastic pools + url: https://learn.microsoft.com/azure/azure-sql/database/elastic-pool-overview diff --git a/azext_prototype/governance/policies/cost/sku-selection.policy.yaml b/azext_prototype/governance/policies/cost/sku-selection.policy.yaml new file mode 100644 index 0000000..b7a1163 --- /dev/null +++ b/azext_prototype/governance/policies/cost/sku-selection.policy.yaml @@ -0,0 +1,8876 @@ +kind: policy +domain: cost +description: Governance policies for Sku Selection +last_updated: '2026-03-27' +rules: +- id: WAF-COST-SKU-001 + severity: required + description: Select appropriate compute SKU based on environment tier — B-series for dev/POC, D-series for production + rationale: Compute is typically the largest cost driver; right-sizing by environment prevents overspending on dev while + ensuring production performance + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Web/serverfarms + - Microsoft.App/managedEnvironments + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === App Service Plan: Dev/POC === + resource "azapi_resource" "app_service_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "B1" # Dev/POC: Basic B1 ($13/mo) — 1 core, 1.75 GB RAM + tier = "Basic" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Staging === + resource "azapi_resource" "app_service_plan_staging" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "S1" # Staging: Standard S1 ($73/mo) — 1 core, 1.75 GB RAM, slots, autoscale + tier = "Standard" + } + kind = "linux" + properties = { + reserved = true + } + } + } + + # === App Service Plan: Production === + resource "azapi_resource" "app_service_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.app_service_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "P1v3" # Production: Premium P1v3 ($138/mo) — 2 cores, 8 GB RAM, VNet, slots + tier = "PremiumV3" + } + kind = "linux" + properties = { + reserved = true + zoneRedundant = true + } + } + } + + # === Azure Functions: Dev/POC (Consumption) === + resource "azapi_resource" "functions_plan_dev" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Y1" # Dev/POC: Consumption — pay-per-execution, first 1M free + tier = "Dynamic" + } + kind = "functionapp" + properties = { + reserved = true + } + } + } + + # === Azure Functions: Production (Elastic Premium) === + resource "azapi_resource" "functions_plan_prod" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.functions_plan_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "EP1" # Production: Elastic Premium EP1 ($155/mo) — 1 core, 3.5 GB RAM, VNet, always-ready + tier = "ElasticPremium" + } + kind = "functionapp" + properties = { + reserved = true + maximumElasticWorkerCount = 20 + } + } + } + + # === Container Apps: Dev/POC (Consumption) === + resource "azapi_resource" "container_app_env_dev" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" # Dev/POC: pay-per-use, no idle cost + } + ] + } + } + } + + # === Container Apps: Production (Dedicated D4) === + resource "azapi_resource" "container_app_env_prod" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_env_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + zoneRedundant = true + workloadProfiles = [ + { + name = "Consumption" + workloadProfileType = "Consumption" + }, + { + name = "dedicated" + workloadProfileType = "D4" # Production: Dedicated D4 — 4 cores, 16 GB RAM + minimumCount = 1 + maximumCount = 10 + } + ] + } + } + } + + # === Virtual Machine: Dev/POC === + resource "azapi_resource" "vm_dev" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_B2s" # Dev/POC: B-series burstable — 2 cores, 4 GB RAM (~$30/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Standard_LRS" # Dev: Standard HDD is sufficient + } + } + } + } + } + } + + # === Virtual Machine: Production === + resource "azapi_resource" "vm_prod" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + hardwareProfile = { + vmSize = "Standard_D4s_v5" # Production: D-series — 4 cores, 16 GB RAM (~$140/mo) + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_LRS" # Production: Premium SSD for IOPS + } + } + } + } + } + } + bicep_pattern: | + // === App Service Plan: Dev/POC === + resource appServicePlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'B1' // Dev/POC: Basic B1 ($13/mo) + tier: 'Basic' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Staging === + resource appServicePlanStaging 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'S1' // Staging: Standard S1 ($73/mo) — slots, autoscale + tier: 'Standard' + } + properties: { + reserved: true + } + } + + // === App Service Plan: Production === + resource appServicePlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: appServicePlanName + location: location + kind: 'linux' + sku: { + name: 'P1v3' // Production: Premium P1v3 ($138/mo) — VNet, slots, zone-redundant + tier: 'PremiumV3' + } + properties: { + reserved: true + zoneRedundant: true + } + } + + // === Azure Functions: Dev/POC (Consumption) === + resource functionsPlanDev 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'Y1' // Dev/POC: Consumption — pay-per-execution + tier: 'Dynamic' + } + properties: { + reserved: true + } + } + + // === Azure Functions: Production (Elastic Premium) === + resource functionsPlanProd 'Microsoft.Web/serverfarms@2023-12-01' = { + name: functionsPlanName + location: location + kind: 'functionapp' + sku: { + name: 'EP1' // Production: Elastic Premium EP1 ($155/mo) — VNet, always-ready + tier: 'ElasticPremium' + } + properties: { + reserved: true + maximumElasticWorkerCount: 20 + } + } + + // === Container Apps Environment: Dev/POC === + resource containerAppEnvDev 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' // Dev/POC: pay-per-use + } + ] + } + } + + // === Container Apps Environment: Production === + resource containerAppEnvProd 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerEnvName + location: location + properties: { + zoneRedundant: true + workloadProfiles: [ + { + name: 'Consumption' + workloadProfileType: 'Consumption' + } + { + name: 'dedicated' + workloadProfileType: 'D4' // Production: Dedicated D4 — 4 cores, 16 GB + minimumCount: 1 + maximumCount: 10 + } + ] + } + } + + // === Virtual Machine: Dev/POC === + resource vmDev 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_B2s' // Dev/POC: Burstable — 2 cores, 4 GB (~$30/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Standard_LRS' + } + } + } + } + } + + // === Virtual Machine: Production === + resource vmProd 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + properties: { + hardwareProfile: { + vmSize: 'Standard_D4s_v5' // Production: D-series — 4 cores, 16 GB (~$140/mo) + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_LRS' + } + } + } + } + } + prohibitions: + - NEVER use Premium/PremiumV3 App Service Plans for dev/POC without written justification + - NEVER use Elastic Premium Functions plan for dev/POC — use Consumption (Y1) + - NEVER use D-series or F-series VMs for dev/POC — use B-series burstable + - NEVER use Dedicated workload profiles in Container Apps for dev/POC — use Consumption + - NEVER deploy Classic Cloud Services (PaaS) — use App Service or Container Apps + - NEVER use A-series or legacy VM SKUs — they are deprecated and cost-inefficient +- id: WAF-COST-SKU-002 + severity: required + description: Select appropriate database SKU based on environment tier — serverless/burstable for dev, provisioned/GP for + production + rationale: Database costs can exceed compute; serverless and burstable tiers eliminate idle costs in dev + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === Azure SQL: Dev/POC (Serverless) === + resource "azapi_resource" "sql_database_dev" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # Dev/POC: Serverless Gen5 — auto-pause, pay-per-vCore-second + tier = "GeneralPurpose" + family = "Gen5" + capacity = 1 # Min 0.5 vCores when active + } + properties = { + autoPauseDelay = 60 # Auto-pause after 60 minutes idle + minCapacity = 0.5 # Scale down to 0.5 vCores + maxSizeBytes = 34359738368 # 32 GB max + zoneRedundant = false + requestedBackupStorageRedundancy = "Local" # LRS backup for dev + } + } + } + + # === Azure SQL: Production (Provisioned GP) === + resource "azapi_resource" "sql_database_prod" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_Gen5" # Production: Provisioned Gen5 — predictable performance + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # 2 vCores + } + properties = { + maxSizeBytes = 107374182400 # 100 GB + zoneRedundant = true + requestedBackupStorageRedundancy = "Geo" # GRS backup for production + readScale = "Enabled" + } + } + } + + # === Cosmos DB: Dev/POC (Serverless) === + resource "azapi_resource" "cosmos_account_dev" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = var.location + failoverPriority = 0 + } + ] + capabilities = [ + { + name = "EnableServerless" # Dev/POC: Serverless — no idle cost, pay per RU consumed + } + ] + } + } + } + + # === Cosmos DB: Production (Autoscale) === + resource "azapi_resource" "cosmos_database_prod" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.cosmos_database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.cosmos_database_name + } + options = { + autoscaleSettings = { + maxThroughput = 4000 # Production: Autoscale — scales 10%-100% of max (400-4000 RU/s) + } + } + } + } + } + + # === PostgreSQL Flexible: Dev/POC (Burstable) === + resource "azapi_resource" "postgres_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_B1ms" # Dev/POC: Burstable B1ms — 1 vCore, 2 GB RAM (~$13/mo) + tier = "Burstable" + } + properties = { + version = "16" + storage = { + storageSizeGB = 32 + autoGrow = "Disabled" # Dev: fixed storage to control costs + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Dev: no geo-backup needed + } + } + } + } + + # === PostgreSQL Flexible: Production (General Purpose) === + resource "azapi_resource" "postgres_prod" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.postgres_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_D2s_v3" # Production: GP D2s_v3 — 2 vCores, 8 GB RAM (~$125/mo) + tier = "GeneralPurpose" + } + properties = { + version = "16" + storage = { + storageSizeGB = 128 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 35 + geoRedundantBackup = "Enabled" # Production: geo-redundant backup + } + highAvailability = { + mode = "ZoneRedundant" + } + } + } + } + bicep_pattern: | + // === Azure SQL: Dev/POC (Serverless) === + resource sqlDatabaseDev 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_S_Gen5' // Dev/POC: Serverless Gen5 — auto-pause, pay per vCore-second + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 1 + } + properties: { + autoPauseDelay: 60 + minCapacity: json('0.5') + maxSizeBytes: 34359738368 // 32 GB + zoneRedundant: false + requestedBackupStorageRedundancy: 'Local' + } + } + + // === Azure SQL: Production (Provisioned GP) === + resource sqlDatabaseProd 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' // Production: Provisioned Gen5 + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + maxSizeBytes: 107374182400 // 100 GB + zoneRedundant: true + requestedBackupStorageRedundancy: 'Geo' + readScale: 'Enabled' + } + } + + // === Cosmos DB: Dev/POC (Serverless) === + resource cosmosAccountDev 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + capabilities: [ + { + name: 'EnableServerless' // Dev/POC: no idle cost + } + ] + } + } + + // === Cosmos DB: Production (Autoscale) === + resource cosmosDatabaseProd 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: cosmosDatabaseName + properties: { + resource: { + id: cosmosDatabaseName + } + options: { + autoscaleSettings: { + maxThroughput: 4000 // Production: 400-4000 RU/s autoscale + } + } + } + } + + // === PostgreSQL Flexible: Dev/POC (Burstable) === + resource postgresDev 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_B1ms' // Dev/POC: Burstable — 1 vCore, 2 GB (~$13/mo) + tier: 'Burstable' + } + properties: { + version: '16' + storage: { + storageSizeGB: 32 + autoGrow: 'Disabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + } + } + + // === PostgreSQL Flexible: Production (General Purpose) === + resource postgresProd 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: postgresName + location: location + sku: { + name: 'Standard_D2s_v3' // Production: GP — 2 vCores, 8 GB (~$125/mo) + tier: 'GeneralPurpose' + } + properties: { + version: '16' + storage: { + storageSizeGB: 128 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + highAvailability: { + mode: 'ZoneRedundant' + } + } + } + prohibitions: + - NEVER use DTU-based SQL tiers (Basic, S0, S1) — always use vCore serverless or provisioned for cost predictability + - NEVER use provisioned throughput Cosmos DB for dev/POC — use Serverless capability + - NEVER use General Purpose or Memory Optimized PostgreSQL tiers for dev/POC — use Burstable + - NEVER set Cosmos DB fixed throughput (manual RU/s) in production — use autoscale + - NEVER use geo-redundant backup for dev/POC databases +- id: WAF-COST-SKU-003 + severity: required + description: Select appropriate storage redundancy — LRS for dev/POC, GRS or ZRS for production; use tiered access (Hot/Cool/Archive) + rationale: Storage redundancy costs scale linearly; LRS is 2-3x cheaper than GRS. Access tiers reduce costs for infrequently + accessed data + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Storage/storageAccounts + - Microsoft.Network/loadBalancers + - Microsoft.Network/frontDoors + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Cache/redis +- id: WAF-COST-SKU-004 + severity: required + description: Select appropriate networking SKU — Basic for dev/POC, Standard for production + rationale: Networking services vary significantly in cost by tier; Basic SKUs are sufficient for development + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Network/loadBalancers + - Microsoft.Cdn/profiles + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Network/virtualNetworkGateways + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === Load Balancer: Dev/POC (Basic — free) === + resource "azapi_resource" "lb_dev" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" # Dev/POC: Basic LB — free, limited features + tier = "Regional" + } + } + } + + # === Load Balancer: Production (Standard) === + resource "azapi_resource" "lb_prod" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.lb_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard" # Production: Standard LB ($18/mo + rules) — HA ports, AZ support + tier = "Regional" + } + } + } + + # === Front Door: Dev/POC (Standard) === + resource "azapi_resource" "frontdoor_dev" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # Dev/POC: Standard ($35/mo) — CDN + routing + } + } + } + + # === Front Door: Production (Premium) === + resource "azapi_resource" "frontdoor_prod" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.frontdoor_name + location = "global" + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Premium_AzureFrontDoor" # Production: Premium ($330/mo) — WAF, Private Link origins + } + } + } + + # === VPN Gateway: Dev/POC (VpnGw1) === + resource "azapi_resource" "vpn_gw_dev" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw1" # Dev/POC: VpnGw1 (~$140/mo) — 650 Mbps, 30 S2S tunnels + tier = "VpnGw1" + } + } + } + } + + # === VPN Gateway: Production (VpnGw2AZ) === + resource "azapi_resource" "vpn_gw_prod" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = var.vpn_gw_name + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + gatewayType = "Vpn" + vpnType = "RouteBased" + sku = { + name = "VpnGw2AZ" # Production: VpnGw2AZ (~$350/mo) — 1.25 Gbps, AZ-redundant + tier = "VpnGw2AZ" + } + } + } + } + bicep_pattern: | + // === Load Balancer: Dev/POC (Basic — free) === + resource lbDev 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Basic' + tier: 'Regional' + } + } + + // === Load Balancer: Production (Standard) === + resource lbProd 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: lbName + location: location + sku: { + name: 'Standard' + tier: 'Regional' + } + } + + // === Front Door: Dev/POC (Standard) === + resource frontDoorDev 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Standard_AzureFrontDoor' // Dev/POC: $35/mo + } + } + + // === Front Door: Production (Premium) === + resource frontDoorProd 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' // Production: $330/mo — WAF, Private Link + } + } + + // === VPN Gateway: Dev/POC === + resource vpnGwDev 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw1' // Dev/POC: ~$140/mo, 650 Mbps + tier: 'VpnGw1' + } + } + } + + // === VPN Gateway: Production === + resource vpnGwProd 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: vpnGwName + location: location + properties: { + gatewayType: 'Vpn' + vpnType: 'RouteBased' + sku: { + name: 'VpnGw2AZ' // Production: ~$350/mo, 1.25 Gbps, AZ-redundant + tier: 'VpnGw2AZ' + } + } + } + prohibitions: + - NEVER use Premium Front Door for dev/POC — Standard is sufficient + - NEVER use VpnGw3/VpnGw4/VpnGw5 for dev/POC — VpnGw1 provides adequate throughput + - NEVER use Basic Load Balancer for production — it lacks availability zone support and SLA + - NEVER use legacy VPN Gateway SKUs (Basic) — they do not support IKEv2 or active-active + - NEVER deploy Application Gateway WAF v1 — use v2 for autoscaling and zone-redundancy +- id: WAF-COST-SKU-005 + severity: required + description: Select appropriate cache SKU — Basic C0 for dev/POC, Standard C1+ for staging, Premium for production clustering + rationale: Redis cache pricing varies 10x between tiers; Basic is sufficient for development caching scenarios + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - cost-analyst + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Compute/virtualMachines + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis + - Microsoft.Network/loadBalancers + - Microsoft.Network/frontDoors + - Microsoft.Network/virtualNetworkGateways +patterns: +- name: Environment-tiered SKU selection + description: 'Select SKUs based on environment: dev/POC uses lowest viable tier, production uses appropriate performance + tier with redundancy' +anti_patterns: +- description: Do not use the same SKU for dev and production environments + instead: Use tiered SKU selection — burstable/basic/consumption for dev, standard/premium for production +- description: Do not select SKUs based solely on feature availability + instead: Balance features against cost — many premium features are unnecessary for POC validation +- description: Do not use Classic or deprecated resource types + instead: Use current-generation resource types (StorageV2, Gen5 SQL, Flexible PostgreSQL) +references: +- title: Azure pricing calculator + url: https://azure.microsoft.com/pricing/calculator/ +- title: App Service pricing + url: https://azure.microsoft.com/pricing/details/app-service/ +- title: Azure SQL Database pricing + url: https://azure.microsoft.com/pricing/details/azure-sql-database/ +- title: Cosmos DB pricing + url: https://azure.microsoft.com/pricing/details/cosmos-db/ +- title: Azure Cache for Redis pricing + url: https://azure.microsoft.com/pricing/details/cache/ diff --git a/azext_prototype/governance/policies/integration/api-patterns.policy.yaml b/azext_prototype/governance/policies/integration/api-patterns.policy.yaml new file mode 100644 index 0000000..b8f9245 --- /dev/null +++ b/azext_prototype/governance/policies/integration/api-patterns.policy.yaml @@ -0,0 +1,110 @@ +kind: policy +domain: integration +description: Governance policies for Api Patterns +last_updated: '2026-03-27' +rules: +- id: CC-INT-API-001 + severity: required + description: Implement API versioning using URL path segments in APIM with version sets + rationale: API versioning prevents breaking changes for existing consumers; URL path versioning is the most discoverable + approach + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ApiManagement/service/apiVersionSets@2023-09-01-preview + name: api-version-set + description: API version set grouping related API versions under a single path + - type: Microsoft.ApiManagement/service/apis/policies@2023-09-01-preview + name: deprecation-policy + description: Outbound policy adding Sunset and Deprecation headers to deprecated API versions + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: CC-INT-API-002 + severity: required + description: Configure OAuth 2.0 / JWT validation in APIM inbound policies for all API endpoints + rationale: APIs without authentication allow unrestricted access; JWT validation at the gateway prevents unauthorized requests + from reaching backends + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ApiManagement/service/authorizationServers@2023-09-01-preview + name: entra-id-oauth + description: OAuth 2.0 authorization server for Entra ID integration in developer portal + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: CC-INT-API-003 + severity: required + description: Configure request and response validation policies in APIM to enforce API contracts + rationale: Request validation prevents malformed input from reaching backends; response validation ensures API contract + compliance + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: CC-INT-API-004 + severity: recommended + description: Integrate OpenAPI specification with APIM for auto-generated documentation and developer portal + rationale: OpenAPI specs provide machine-readable API contracts; APIM developer portal auto-generates interactive documentation + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.Web/sites + - Microsoft.App/containerApps +patterns: +- name: Versioned API with APIM version sets + description: URL path-segmented API versioning with sunset headers on deprecated versions +- name: JWT-validated API with Entra ID + description: APIM inbound JWT validation using Entra ID OpenID Connect discovery +- name: OpenAPI-driven API with request validation + description: API imported from OpenAPI spec with inbound content and parameter validation +anti_patterns: +- description: Do not deploy APIs without versioning + instead: Use APIM API version sets with URL segment versioning (v1, v2) +- description: Do not deploy APIs without authentication + instead: Configure validate-jwt policy with Entra ID OpenID Connect discovery +- description: Do not skip request validation + instead: Use validate-content and validate-parameters policies with OpenAPI schema enforcement +- description: Do not expose internal error details in API responses + instead: Use on-error policy to return RFC 9457 Problem Details format +references: +- title: APIM API versioning + url: https://learn.microsoft.com/azure/api-management/api-management-versions +- title: APIM JWT validation + url: https://learn.microsoft.com/azure/api-management/validate-jwt-policy +- title: APIM content validation + url: https://learn.microsoft.com/azure/api-management/validate-content-policy +- title: APIM OpenAPI import + url: https://learn.microsoft.com/azure/api-management/import-api-from-oas +- title: RFC 9457 Problem Details + url: https://www.rfc-editor.org/rfc/rfc9457 diff --git a/azext_prototype/governance/policies/integration/apim-to-container-apps.policy.yaml b/azext_prototype/governance/policies/integration/apim-to-container-apps.policy.yaml index e9badd2..7fd8a1d 100644 --- a/azext_prototype/governance/policies/integration/apim-to-container-apps.policy.yaml +++ b/azext_prototype/governance/policies/integration/apim-to-container-apps.policy.yaml @@ -1,74 +1,107 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: apim-to-container-apps - category: integration - services: [api-management, container-apps] - last_reviewed: "2025-12-01" - -rules: - - id: INT-001 - severity: required - description: "Route all external API traffic through API Management" - rationale: "Centralizes auth, rate limiting, and observability" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - require_service: [api-management] - when_services_present: [container-apps] - severity: warning - error_message: "Template has container-apps but no api-management gateway" - - - id: INT-002 - severity: required - description: "Use APIM managed identity to authenticate to Container Apps" - rationale: "No shared keys or certificates between services" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [api-management] - when_services_present: [container-apps] - require_config: [identity] - error_message: "Service '{service_name}' ({service_type}) missing managed identity for authenticating to Container Apps" - - - id: INT-003 - severity: recommended - description: "Set Container App ingress to internal-only when fronted by APIM" - rationale: "Container App should not be directly accessible from the internet" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - template_check: - scope: [container-apps] - when_services_present: [api-management] - require_config_value: - ingress: internal - error_message: "Service '{service_name}' ({service_type}) should set ingress: internal when APIM is the external gateway" - - - id: INT-004 - severity: recommended - description: "Configure APIM caching policies for read-heavy endpoints" - rationale: "Reduces backend load and improves response latency" - applies_to: [cloud-architect, app-developer] - template_check: - scope: [api-management] - when_services_present: [container-apps] - require_config: [caching] - error_message: "Service '{service_name}' ({service_type}) missing caching: true for read-heavy endpoints" - -patterns: - - name: "APIM backend with managed identity" - description: "Configure APIM backend pointing to internal Container App" - example: | - resource "azurerm_api_management_backend" "container_app" { - name = "container-app-backend" - resource_group_name = azurerm_resource_group.main.name - api_management_name = azurerm_api_management.main.name - protocol = "http" - url = "https://${azurerm_container_app.api.latest_revision_fqdn}" - } - -anti_patterns: - - description: "Do not expose Container App endpoints directly to the internet" - instead: "Use APIM as the gateway; set Container App ingress to internal" - -references: - - title: "APIM with Container Apps" - url: "https://learn.microsoft.com/azure/api-management/integrate-container-app" +kind: policy +domain: integration +description: Governance policies for Apim To Container Apps +last_updated: '2025-12-01' +rules: +- id: CC-INT-APIM-001 + severity: required + description: Route all external API traffic through API Management + rationale: Centralizes auth, rate limiting, and observability + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + template_check: + require_service: + - api-management + when_services_present: + - container-apps + severity: warning + error_message: Template has container-apps but no api-management gateway + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.App/containerApps +- id: CC-INT-APIM-002 + severity: required + description: Use APIM managed identity to authenticate to Container Apps + rationale: No shared keys or certificates between services + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + template_check: + scope: + - api-management + when_services_present: + - container-apps + require_config: + - identity + error_message: Service '{service_name}' ({service_type}) missing managed identity for authenticating to Container Apps + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.App/containerApps +- id: CC-INT-APIM-003 + severity: recommended + description: Set Container App ingress to internal-only when fronted by APIM + rationale: Container App should not be directly accessible from the internet + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + template_check: + scope: + - container-apps + when_services_present: + - api-management + require_config_value: + ingress: internal + error_message: 'Service ''{service_name}'' ({service_type}) should set ingress: internal when APIM is the external gateway' + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.App/containerApps +- id: CC-INT-APIM-004 + severity: recommended + description: Configure APIM caching policies for read-heavy endpoints + rationale: Reduces backend load and improves response latency + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + template_check: + scope: + - api-management + when_services_present: + - container-apps + require_config: + - caching + error_message: 'Service ''{service_name}'' ({service_type}) missing caching: true for read-heavy endpoints' + targets: + - services: + - Microsoft.ApiManagement/service + - Microsoft.App/containerApps +patterns: +- name: APIM backend with managed identity + description: Configure APIM backend pointing to internal Container App + example: | + resource "azapi_resource" "apim_backend_container_app" { + type = "Microsoft.ApiManagement/service/backends@2023-09-01-preview" + parent_id = azapi_resource.api_management.id + name = "container-app-backend" + body = { + properties = { + protocol = "http" + url = "https://${azapi_resource.container_app_api.output.properties.latestRevisionFqdn}" + } + } + } +anti_patterns: +- description: Do not expose Container App endpoints directly to the internet + instead: Use APIM as the gateway; set Container App ingress to internal +references: +- title: APIM with Container Apps + url: https://learn.microsoft.com/azure/api-management/integrate-container-app diff --git a/azext_prototype/governance/policies/integration/data-pipeline.policy.yaml b/azext_prototype/governance/policies/integration/data-pipeline.policy.yaml new file mode 100644 index 0000000..e2988ec --- /dev/null +++ b/azext_prototype/governance/policies/integration/data-pipeline.policy.yaml @@ -0,0 +1,160 @@ +kind: policy +domain: integration +description: Governance policies for Data Pipeline +last_updated: '2026-03-27' +rules: +- id: CC-INT-DP-001 + severity: required + description: Configure Data Factory linked services to SQL Database and Storage using managed identity — never stored credentials + rationale: Managed identity eliminates credential rotation burden and prevents secret sprawl across linked services + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.DataFactory/factories/managedVirtualNetworks@2018-06-01 + name: default + description: Managed VNet for ADF to enable managed private endpoints + - type: Microsoft.DataFactory/factories/integrationRuntimes@2018-06-01 + name: ManagedVNetIR + description: Managed VNet integration runtime — all data movement stays on Azure backbone + - type: Microsoft.DataFactory/factories/managedVirtualNetworks/managedPrivateEndpoints@2018-06-01 + name: mpe-sql + description: Managed private endpoint from ADF to SQL Database + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: adf-storage-contributor + description: Storage Blob Data Contributor role for ADF managed identity + template_check: + when_services_present: + - data-factory + - azure-sql + require_service: + - key-vault + severity: warning + error_message: Data Factory + SQL template must include Key Vault for secret management in linked services + targets: + - services: + - Microsoft.DataFactory/factories + - Microsoft.Synapse/workspaces + - Microsoft.Databricks/workspaces + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers +- id: CC-INT-DP-002 + severity: required + description: Configure Synapse Workspace with ADLS Gen2 default data lake using managed identity and managed private endpoints + rationale: Synapse requires a default data lake for workspace artifacts; managed identity eliminates storage account keys + in configuration + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + companion_resources: + - type: Microsoft.Storage/storageAccounts@2023-05-01 + name: synapse-data-lake + description: 'ADLS Gen2 storage account (isHnsEnabled: true) for Synapse default data lake' + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: synapse-storage-contributor + description: Storage Blob Data Contributor role for Synapse managed identity on data lake + - type: Microsoft.Synapse/workspaces/managedVirtualNetworks/managedPrivateEndpoints@2021-06-01 + name: mpe-datalake-dfs + description: Managed private endpoint for Synapse to access data lake DFS endpoint + template_check: + when_services_present: + - synapse-workspace + require_service: + - storage-account + severity: error + error_message: Synapse workspace requires a storage account with ADLS Gen2 (isHnsEnabled) as default data lake + targets: + - services: + - Microsoft.DataFactory/factories + - Microsoft.Synapse/workspaces + - Microsoft.Databricks/workspaces + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers +- id: CC-INT-DP-003 + severity: required + description: Configure Databricks workspace with Key Vault-backed secret scope for secure credential access + rationale: Databricks secret scopes backed by Key Vault centralize secret management; Azure-managed scopes lack audit trail + and rotation + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.KeyVault/vaults@2023-07-01 + name: dbr-key-vault + description: Key Vault with RBAC authorization for Databricks secret scope backing store + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-dbr-kv + description: Private endpoint for Key Vault access from Databricks VNet + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: dbr-kv-secrets-user + description: Key Vault Secrets User role (4633458b) for Databricks workspace identity + template_check: + when_services_present: + - databricks + require_service: + - key-vault + severity: warning + error_message: Databricks template must include Key Vault for Key Vault-backed secret scopes + targets: + - services: + - Microsoft.DataFactory/factories + - Microsoft.Synapse/workspaces + - Microsoft.Databricks/workspaces + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers +- id: CC-INT-DP-004 + severity: required + description: Enforce encryption in transit for all cross-service data movement using private endpoints and TLS 1.2+ + rationale: Data in transit between services must be encrypted and routed privately to prevent interception and exfiltration + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - security-reviewer + companion_resources: + - type: Microsoft.Network/privateEndpoints@2024-01-01 + name: pe-sql + description: Private endpoint for SQL Server with groupId 'sqlServer' + - type: Microsoft.Network/privateDnsZones@2024-06-01 + name: privatelink.database.windows.net + description: Private DNS zone for SQL Server private endpoint resolution + targets: + - services: + - Microsoft.DataFactory/factories + - Microsoft.Synapse/workspaces + - Microsoft.Databricks/workspaces + - Microsoft.Storage/storageAccounts + - Microsoft.Sql/servers +patterns: +- name: Data Factory to SQL and Storage with managed identity + description: ADF with managed VNet IR, managed private endpoints to SQL and Storage, Key Vault for secrets +- name: Synapse with ADLS Gen2 data lake + description: Synapse workspace with ADLS Gen2 default storage, managed private endpoints, and Storage Blob Data Contributor + role +- name: Databricks with Key Vault secret scope + description: Databricks Premium workspace with Key Vault-backed secret scope via REST API, RBAC authorization +anti_patterns: +- description: Do not store credentials in Data Factory or Synapse linked service definitions + instead: Use managed identity with RBAC roles or Key Vault references for all data source connections +- description: Do not use public endpoints for data movement between services + instead: Use managed private endpoints (ADF/Synapse) or private endpoints with private DNS zones +- description: Do not use Databricks-managed secret scopes in production + instead: Use Key Vault-backed secret scopes with RBAC authorization and audit logging +references: +- title: Data Factory managed private endpoints + url: https://learn.microsoft.com/azure/data-factory/managed-virtual-network-private-endpoint +- title: Synapse managed private endpoints + url: https://learn.microsoft.com/azure/synapse-analytics/security/synapse-workspace-managed-private-endpoints +- title: Databricks Key Vault-backed secret scopes + url: https://learn.microsoft.com/azure/databricks/security/secrets/secret-scopes +- title: Data Factory identity-based authentication + url: https://learn.microsoft.com/azure/data-factory/connector-azure-blob-storage#managed-identity diff --git a/azext_prototype/governance/policies/integration/event-driven.policy.yaml b/azext_prototype/governance/policies/integration/event-driven.policy.yaml new file mode 100644 index 0000000..5f5892a --- /dev/null +++ b/azext_prototype/governance/policies/integration/event-driven.policy.yaml @@ -0,0 +1,173 @@ +kind: policy +domain: integration +description: Governance policies for Event Driven +last_updated: '2026-03-27' +rules: +- id: CC-INT-ED-001 + severity: required + description: Wire Event Grid subscriptions to Function App or Container App endpoints with dead-letter storage and managed + identity delivery + rationale: Event Grid provides at-least-once delivery; dead-letter captures undeliverable events; managed identity eliminates + connection strings + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.EventGrid/systemTopics@2024-06-01-preview + name: system-topic + description: System topic with managed identity for secure event delivery + - type: Microsoft.Storage/storageAccounts@2023-05-01 + name: dead-letter-storage + description: Storage account with blob container for dead-letter event capture + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: eg-dlq-role + description: Storage Blob Data Contributor role for Event Grid to write dead-letter blobs + template_check: + when_services_present: + - event-grid + - functions + require_service: + - storage-account + severity: warning + error_message: Event Grid + Functions template must include a storage account for dead-letter configuration + targets: + - services: + - Microsoft.EventGrid/topics + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.StreamAnalytics/streamingjobs +- id: CC-INT-ED-002 + severity: required + description: Wire Service Bus triggers to Function App or Container App using managed identity connections + rationale: Service Bus provides reliable ordered messaging; managed identity eliminates connection string management and + rotation burden + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: fn-sb-data-receiver + description: Azure Service Bus Data Receiver role (4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0) for Function App identity + template_check: + when_services_present: + - service-bus + - functions + require_service: + - managed-identity + severity: warning + error_message: Service Bus + Functions template must include managed identity for connection string-free triggers + targets: + - services: + - Microsoft.EventGrid/topics + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.StreamAnalytics/streamingjobs +- id: CC-INT-ED-003 + severity: required + description: Wire Event Hubs to Stream Analytics to Storage/SQL for real-time stream processing pipelines + rationale: Event Hubs provides high-throughput ingestion; Stream Analytics handles windowed aggregation; output to durable + storage completes the pipeline + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01 + name: asa-consumer-group + description: Dedicated consumer group for Stream Analytics — never use $Default + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: asa-eh-receiver + description: Azure Event Hubs Data Receiver role for Stream Analytics managed identity + targets: + - services: + - Microsoft.EventGrid/topics + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.StreamAnalytics/streamingjobs +- id: CC-INT-ED-004 + severity: required + description: Configure dead-letter queues for Service Bus and dead-letter storage for Event Grid + rationale: Dead-letter captures messages/events that cannot be delivered or processed, enabling investigation and replay + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.EventGrid/topics + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.StreamAnalytics/streamingjobs +- id: CC-INT-ED-005 + severity: required + description: Implement poison message handling patterns for failed message processing + rationale: Poison messages that repeatedly fail processing block other messages; explicit handling prevents queue stalls + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + companion_resources: + - type: Microsoft.Insights/metricAlerts@2018-03-01 + name: dlq-depth-alert + description: Alert when dead-letter queue depth exceeds threshold — triggers investigation + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ops-action-group + description: Action group for dead-letter alerts — email and webhook notifications + targets: + - services: + - Microsoft.EventGrid/topics + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.StreamAnalytics/streamingjobs +patterns: +- name: Event Grid to Function App with dead-letter + description: System topic subscription delivering to Azure Function with managed identity and dead-letter storage +- name: Service Bus trigger with managed identity + description: Function App consuming Service Bus queue using managed identity connection string-free binding +- name: Event Hub to Stream Analytics pipeline + description: Real-time stream processing with Event Hub input, Stream Analytics windowed query, and blob output +anti_patterns: +- description: Do not use connection strings for event source authentication + instead: Use managed identity with RBAC role assignments for all event source connections +- description: Do not skip dead-letter configuration on any event subscription or queue + instead: Always configure dead-letter storage for Event Grid and ensure deadLetteringOnMessageExpiration for Service Bus +- description: Do not process events without idempotency checks + instead: Use message deduplication (requiresDuplicateDetection) and implement idempotent event handlers +references: +- title: Event Grid dead-letter and retry + url: https://learn.microsoft.com/azure/event-grid/delivery-and-retry +- title: Service Bus dead-letter queues + url: https://learn.microsoft.com/azure/service-bus-messaging/service-bus-dead-letter-queues +- title: Azure Functions Service Bus trigger + url: https://learn.microsoft.com/azure/azure-functions/functions-bindings-service-bus-trigger +- title: Stream Analytics with Event Hubs + url: https://learn.microsoft.com/azure/stream-analytics/stream-analytics-define-inputs +- title: Event Grid managed identity delivery + url: https://learn.microsoft.com/azure/event-grid/managed-service-identity diff --git a/azext_prototype/governance/policies/integration/frontend-backend.policy.yaml b/azext_prototype/governance/policies/integration/frontend-backend.policy.yaml new file mode 100644 index 0000000..ba84151 --- /dev/null +++ b/azext_prototype/governance/policies/integration/frontend-backend.policy.yaml @@ -0,0 +1,129 @@ +kind: policy +domain: integration +description: Governance policies for Frontend Backend +last_updated: '2026-03-27' +rules: +- id: CC-INT-FB-001 + severity: required + description: Configure Static Web App with linked backend API for managed API routing and authentication passthrough + rationale: Linked backends provide managed routing from SWA to API backends; authentication context is automatically forwarded + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Web/staticSites/linkedBackends@2023-12-01 + name: api-backend + description: Linked backend routing /api/* requests from SWA to Container App or Functions + - type: Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31 + name: id-api + description: User-assigned managed identity for the API backend + template_check: + when_services_present: + - static-web-apps + - container-apps + require_config: + - linked_backend + severity: warning + error_message: Static Web App + Container Apps template should use linked backend for API routing + targets: + - services: + - Microsoft.Web/staticSites + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Network/frontDoors +- id: CC-INT-FB-002 + severity: required + description: Configure CORS with explicit allowed origins on all API backends serving browser-based frontends + rationale: CORS misconfiguration either blocks legitimate frontends or exposes APIs to cross-origin attacks + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/staticSites + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Network/frontDoors +- id: CC-INT-FB-003 + severity: required + description: Configure Azure Front Door or CDN with origin groups for frontend + API backend routing + rationale: Front Door provides global load balancing, WAF protection, and edge caching; origin groups separate static and + API traffic + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + companion_resources: + - type: Microsoft.Cdn/profiles/originGroups@2024-02-01 + name: og-frontend + description: Origin group for static frontend with health probes + - type: Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01 + name: route-frontend + description: Route for /* to frontend origin group with caching enabled + - type: Microsoft.Cdn/profiles/securityPolicies@2024-02-01 + name: waf-policy + description: WAF security policy applied to the Front Door endpoint + targets: + - services: + - Microsoft.Web/staticSites + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Network/frontDoors +- id: CC-INT-FB-004 + severity: required + description: Configure authentication using Easy Auth (App Service/Functions) or MSAL (SPA) with Entra ID + rationale: Authentication must be enforced at the platform or application level; Easy Auth handles token validation without + application code changes + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Web/sites/config@2023-12-01 + name: authsettingsV2 + description: Easy Auth v2 configuration for App Service with Entra ID provider + - type: Microsoft.Web/staticSites/config@2023-12-01 + name: appsettings + description: SWA app settings containing auth client ID and Key Vault-backed client secret + targets: + - services: + - Microsoft.Web/staticSites + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.Network/frontDoors +patterns: +- name: SWA with linked Container App backend + description: Static Web App routing /api/* to Container App via linked backend with auth passthrough +- name: Front Door with split frontend/API routing + description: Front Door with separate origin groups for SWA frontend (cached) and API backend (uncached, private link) +- name: Easy Auth with Entra ID + description: Platform-level authentication via Easy Auth v2 with Entra ID OpenID Connect provider +anti_patterns: +- description: Do not serve APIs without CORS restrictions from browser-based frontends + instead: Configure explicit allowed origins matching the frontend domain +- description: Do not expose backend services directly without CDN or gateway + instead: Use Front Door or SWA linked backend for frontend-to-API routing +- description: Do not use default GitHub auth for enterprise applications + instead: Configure custom Entra ID authentication via Easy Auth or MSAL +references: +- title: Static Web Apps linked backends + url: https://learn.microsoft.com/azure/static-web-apps/apis-container-apps +- title: Front Door origin groups + url: https://learn.microsoft.com/azure/frontdoor/origin +- title: App Service Easy Auth + url: https://learn.microsoft.com/azure/app-service/overview-authentication-authorization +- title: Static Web Apps custom authentication + url: https://learn.microsoft.com/azure/static-web-apps/authentication-custom +- title: Container Apps CORS policy + url: https://learn.microsoft.com/azure/container-apps/cors diff --git a/azext_prototype/governance/policies/integration/microservices.policy.yaml b/azext_prototype/governance/policies/integration/microservices.policy.yaml new file mode 100644 index 0000000..8335ec3 --- /dev/null +++ b/azext_prototype/governance/policies/integration/microservices.policy.yaml @@ -0,0 +1,140 @@ +kind: policy +domain: integration +description: Governance policies for Microservices +last_updated: '2026-03-27' +rules: +- id: CC-INT-MS-001 + severity: required + description: Authenticate service-to-service calls via managed identity and RBAC — never shared keys or hardcoded tokens + rationale: Managed identity eliminates credential management between microservices; RBAC provides auditable access control + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31 + name: id-svc-* + description: User-assigned managed identity per microservice for cross-service authentication + template_check: + scope: + - container-apps + require_config: + - identity + error_message: Service '{service_name}' ({service_type}) missing managed identity for service-to-service authentication + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Insights/components +- id: CC-INT-MS-002 + severity: recommended + description: Enable Dapr sidecar for service invocation, pub/sub, and state management in Container Apps + rationale: Dapr provides service discovery, mTLS, pub/sub abstraction, and state management without application-level implementation + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.App/managedEnvironments/daprComponents@2024-03-01 + name: pubsub-servicebus + description: Dapr pub/sub component backed by Azure Service Bus with managed identity + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Insights/components +- id: CC-INT-MS-003 + severity: required + description: Configure distributed tracing with Application Insights and OpenTelemetry for all microservices + rationale: Distributed tracing correlates requests across microservices; without it, debugging cross-service failures is + impossible + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/components@2020-02-02 + name: app-insights + description: Workspace-based Application Insights for distributed tracing and metrics + - type: Microsoft.OperationalInsights/workspaces@2023-09-01 + name: log-analytics + description: Log Analytics workspace backing Application Insights + template_check: + when_services_present: + - container-apps + require_service: + - application-insights + severity: warning + error_message: Microservices template must include Application Insights for distributed tracing + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Insights/components +- id: CC-INT-MS-004 + severity: required + description: Configure health checks (liveness and readiness probes) on all Container Apps and App Service instances + rationale: Health probes enable automatic restart of unhealthy instances and prevent traffic routing to unready services + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Insights/components +- id: CC-INT-MS-005 + severity: recommended + description: Configure circuit breaker and retry patterns using Dapr resiliency policies + rationale: Circuit breakers prevent cascade failures; retries with backoff handle transient errors gracefully + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Insights/components +patterns: +- name: Service-to-service auth via managed identity + description: Container Apps calling each other using user-assigned managed identities and DefaultAzureCredential +- name: Dapr-enabled microservices + description: Container Apps with Dapr sidecar for service invocation, pub/sub, state, and resiliency +- name: Observable microservices + description: All services emit OpenTelemetry traces to shared Application Insights with service.name attribution +anti_patterns: +- description: Do not hardcode service URLs in container images + instead: Use environment variables, Dapr service invocation, or internal DNS for service discovery +- description: Do not skip health probes on any microservice + instead: Configure startup, liveness, and readiness probes with appropriate thresholds +- description: Do not use synchronous calls without circuit breakers + instead: Configure Dapr resiliency policies or application-level circuit breakers with timeouts +references: +- title: Container Apps service-to-service communication + url: https://learn.microsoft.com/azure/container-apps/connect-apps +- title: Container Apps Dapr integration + url: https://learn.microsoft.com/azure/container-apps/dapr-overview +- title: Container Apps health probes + url: https://learn.microsoft.com/azure/container-apps/health-probes +- title: Application Insights with Container Apps + url: https://learn.microsoft.com/azure/container-apps/opentelemetry-agents +- title: Dapr resiliency policies + url: https://docs.dapr.io/operations/resiliency/policies/ diff --git a/azext_prototype/governance/policies/operational-excellence/monitoring-&-observability.policy.yaml b/azext_prototype/governance/policies/operational-excellence/monitoring-&-observability.policy.yaml new file mode 100644 index 0000000..a13ee23 --- /dev/null +++ b/azext_prototype/governance/policies/operational-excellence/monitoring-&-observability.policy.yaml @@ -0,0 +1,131 @@ +kind: policy +domain: performance +description: Governance policies for Monitoring Observability +last_updated: '2026-03-27' +rules: +- id: WAF-OPEX-OBS-001 + severity: required + description: Configure Application Insights with auto-instrumentation for .NET, Python, and Node.js — use connection string, + not instrumentation key + rationale: Application Insights provides request tracking, dependency tracing, and performance metrics. Connection strings + support regional ingestion endpoints + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - monitoring-agent + targets: + - services: + - Microsoft.Insights/components + - Microsoft.OperationalInsights/workspaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service +- id: WAF-OPEX-OBS-002 + severity: required + description: Configure custom metric alerts for key performance indicators — P95 latency, error rate, throughput, and resource + utilization + rationale: Metric alerts provide proactive notification before performance degradation becomes user-visible; without alerts, + issues are discovered by users + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + companion_resources: + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ag-ops + description: Action group for alert notifications — required for metric alerts to trigger email/webhook/Logic App notifications + targets: + - services: + - Microsoft.Insights/components + - Microsoft.OperationalInsights/workspaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service +- id: WAF-OPEX-OBS-003 + severity: required + description: Enable W3C distributed tracing with trace context propagation across all services in the request chain + rationale: Without distributed tracing, diagnosing performance issues in microservices requires correlating logs across + multiple systems manually. W3C traceparent header provides automatic correlation + applies_to: + - app-developer + - csharp-developer + - python-developer + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Insights/components + - Microsoft.OperationalInsights/workspaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service +- id: WAF-OPEX-OBS-004 + severity: recommended + description: Create standard KQL queries for performance monitoring — P95 latency, error rates, throughput, and slow dependency + calls + rationale: Pre-built KQL queries enable rapid diagnosis during incidents; without them, engineers spend 15-30 minutes writing + queries instead of investigating + applies_to: + - monitoring-agent + - cloud-architect + - qa-engineer + targets: + - services: + - Microsoft.Insights/components + - Microsoft.OperationalInsights/workspaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service +- id: WAF-OPEX-OBS-005 + severity: recommended + description: Configure availability tests for public endpoints — standard URL ping test and multi-step web tests + rationale: Availability tests detect outages from external perspective (outside Azure network); internal health checks may + pass while external access fails + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Insights/components + - Microsoft.OperationalInsights/workspaces + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service +patterns: +- name: Full observability stack + description: Application Insights (auto-instrumentation) + metric alerts (P95, errors, CPU) + distributed tracing (W3C) + + saved KQL queries + availability tests +- name: Three pillars of observability + description: Metrics (alerts, dashboards), Logs (KQL queries, saved searches), Traces (distributed tracing, service map) +anti_patterns: +- description: Do not deploy applications without Application Insights + instead: Enable auto-instrumentation via APPLICATIONINSIGHTS_CONNECTION_STRING on all compute resources +- description: Do not use InstrumentationKey for Application Insights configuration + instead: Use ConnectionString — InstrumentationKey is deprecated and does not support regional ingestion +- description: Do not create alerts without action groups + instead: Configure action groups with email, webhook, or Logic App receivers for all metric alerts +- description: Do not rely solely on internal health probes + instead: Add external availability tests from multiple global locations to detect network-level outages +references: +- title: Application Insights overview + url: https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview +- title: KQL query language reference + url: https://learn.microsoft.com/azure/data-explorer/kusto/query/ +- title: Metric alerts + url: https://learn.microsoft.com/azure/azure-monitor/alerts/alerts-metric-overview +- title: Distributed tracing + url: https://learn.microsoft.com/azure/azure-monitor/app/distributed-trace-data +- title: Availability tests + url: https://learn.microsoft.com/azure/azure-monitor/app/availability-overview diff --git a/azext_prototype/governance/policies/performance/__init__.py b/azext_prototype/governance/policies/performance/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/performance/caching.policy.yaml b/azext_prototype/governance/policies/performance/caching.policy.yaml new file mode 100644 index 0000000..e01a000 --- /dev/null +++ b/azext_prototype/governance/policies/performance/caching.policy.yaml @@ -0,0 +1,135 @@ +kind: policy +domain: performance +description: Governance policies for Caching +last_updated: '2026-03-27' +rules: +- id: WAF-PERF-CACHE-001 + severity: required + description: Configure Azure Cache for Redis with managed identity authentication, connection multiplexing, and appropriate + eviction policy + rationale: Redis is the backbone of distributed caching; misconfigured connections cause connection exhaustion and managed + identity eliminates key rotation burden + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Cache/redis + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.ApiManagement/service + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: WAF-PERF-CACHE-002 + severity: required + description: Configure Front Door or CDN caching with appropriate TTL, cache key customization, and compression + rationale: Edge caching reduces origin load by 70-90% for static content and improves latency from seconds to milliseconds + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Cache/redis + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.ApiManagement/service + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: WAF-PERF-CACHE-003 + severity: recommended + description: Implement application-level cache-aside pattern with distributed cache and local memory fallback + rationale: Cache-aside reduces database load by 80-95% for read-heavy workloads; layered caching (L1 memory + L2 Redis) + minimizes network round-trips + applies_to: + - app-developer + - csharp-developer + - python-developer + - cloud-architect + targets: + - services: + - Microsoft.Cache/redis + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.ApiManagement/service + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: WAF-PERF-CACHE-004 + severity: recommended + description: Configure API Management caching policies for frequently accessed API responses + rationale: APIM built-in cache reduces backend load and latency without application code changes; external Redis cache provides + persistence + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Cache/redis + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.ApiManagement/service + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.App/containerApps +- id: WAF-PERF-CACHE-005 + severity: recommended + description: Enable Cosmos DB integrated cache for read-heavy workloads to reduce RU consumption + rationale: Cosmos DB integrated cache provides item and query cache at the gateway level, reducing RU consumption by 50-90% + for repeated reads + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Cache/redis + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.ApiManagement/service + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Web/sites + - Microsoft.App/containerApps +patterns: +- name: Layered caching strategy + description: L1 in-memory cache (per-instance, <1ms) → L2 Redis cache (distributed, 1-5ms) → L3 CDN/Front Door (edge, <10ms) + → Origin database +- name: Cache key design + description: 'Use hierarchical cache keys: {service}:{entity}:{id}:{version} — enables selective invalidation by prefix' +anti_patterns: +- description: Do not cache everything — only cache data that is read frequently and changes infrequently + instead: Apply cache-aside pattern selectively; monitor cache hit ratio to validate effectiveness +- description: Do not use a single global TTL for all cache entries + instead: 'Set TTL based on data freshness requirements: 30 days for static assets, 5-15 minutes for API data, 30 minutes + for sessions' +- description: Do not cache without monitoring cache hit ratio + instead: Track cache hit/miss ratio via Redis INFO command or Application Insights custom metrics; target >80% hit ratio +- description: Do not serve stale data without a revalidation strategy + instead: 'Use stale-while-revalidate pattern: serve stale data while fetching fresh data in background' +references: +- title: Azure Cache for Redis best practices + url: https://learn.microsoft.com/azure/azure-cache-for-redis/cache-best-practices-development +- title: Front Door caching + url: https://learn.microsoft.com/azure/frontdoor/front-door-caching +- title: APIM caching policies + url: https://learn.microsoft.com/azure/api-management/api-management-caching-policies +- title: Cosmos DB integrated cache + url: https://learn.microsoft.com/azure/cosmos-db/integrated-cache +- title: Cache-aside pattern + url: https://learn.microsoft.com/azure/architecture/patterns/cache-aside diff --git a/azext_prototype/governance/policies/performance/compute.policy.yaml b/azext_prototype/governance/policies/performance/compute.policy.yaml new file mode 100644 index 0000000..33b1ddd --- /dev/null +++ b/azext_prototype/governance/policies/performance/compute.policy.yaml @@ -0,0 +1,121 @@ +kind: policy +domain: performance +description: Governance policies for Compute Optimization +last_updated: '2026-03-27' +rules: +- id: WAF-PERF-COMP-001 + severity: required + description: Define explicit CPU and memory resource limits for Container Apps — prevent unbounded resource consumption + and noisy neighbor issues + rationale: Containers without resource limits can consume all available CPU/memory, starving co-located containers and causing + OOM kills + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.Web/sites + - Microsoft.Compute/virtualMachines +- id: WAF-PERF-COMP-002 + severity: recommended + description: Configure App Service per-app scaling and deployment slots for density optimization and zero-downtime deployments + rationale: Per-app scaling prevents a single app from consuming all plan capacity; slots enable blue-green deployments without + downtime + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.Web/sites + - Microsoft.Compute/virtualMachines +- id: WAF-PERF-COMP-003 + severity: required + description: Define Kubernetes pod resource requests and limits for AKS workloads — prevent scheduling issues and resource + contention + rationale: Pods without requests cannot be scheduled efficiently; pods without limits can starve other workloads. Requests + drive scheduling, limits prevent starvation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.Web/sites + - Microsoft.Compute/virtualMachines +- id: WAF-PERF-COMP-004 + severity: required + description: Configure Azure Functions timeout, concurrency, and batching settings in host.json + rationale: Default Function settings are not optimized for production; incorrect timeout causes failures, incorrect concurrency + causes throttling or resource exhaustion + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.Web/sites + - Microsoft.Compute/virtualMachines +- id: WAF-PERF-COMP-005 + severity: required + description: Offload long-running operations to asynchronous processing with queues and background workers + rationale: Synchronous processing of operations > 5 seconds blocks threads, degrades UX, and causes timeout failures. Async + processing decouples producers from consumers + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.Web/sites + - Microsoft.Compute/virtualMachines +patterns: +- name: Right-sized container resources + description: 'Define CPU/memory based on workload type: API (0.5 CPU/1Gi), worker (0.25 CPU/0.5Gi), data processing (1.0 + CPU/2Gi)' +- name: Async request-reply pattern + description: API returns 202 Accepted with status URL; background worker processes via Service Bus; status endpoint returns + progress +anti_patterns: +- description: Do not run long-running operations in HTTP request handlers + instead: Enqueue to Service Bus and process asynchronously; return 202 Accepted with a status URL +- description: Do not deploy containers or pods without resource limits + instead: Define explicit CPU and memory requests/limits based on workload profiling +- description: Do not deploy directly to production App Service slot + instead: Deploy to staging slot, warm up, then swap to production for zero-downtime deployment +- description: Do not use default Azure Functions host.json settings + instead: Configure timeout, concurrency, batching, and sampling based on workload requirements +references: +- title: Container Apps resource management + url: https://learn.microsoft.com/azure/container-apps/containers +- title: AKS resource management + url: https://learn.microsoft.com/azure/aks/developer-best-practices-resource-management +- title: App Service deployment slots + url: https://learn.microsoft.com/azure/app-service/deploy-staging-slots +- title: Azure Functions host.json reference + url: https://learn.microsoft.com/azure/azure-functions/functions-host-json +- title: Async request-reply pattern + url: https://learn.microsoft.com/azure/architecture/patterns/async-request-reply diff --git a/azext_prototype/governance/policies/performance/database.policy.yaml b/azext_prototype/governance/policies/performance/database.policy.yaml new file mode 100644 index 0000000..e13c4de --- /dev/null +++ b/azext_prototype/governance/policies/performance/database.policy.yaml @@ -0,0 +1,115 @@ +kind: policy +domain: performance +description: Governance policies for Database Optimization +last_updated: '2026-03-27' +rules: +- id: WAF-PERF-DB-001 + severity: required + description: Define SQL indexing strategy — create indexes in deploy.sh post-deployment script for primary query patterns + rationale: Missing indexes cause full table scans; proper indexing can improve query performance by 100-1000x. Indexes are + created post-deployment via T-SQL + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis +- id: WAF-PERF-DB-002 + severity: required + description: Design Cosmos DB partition keys based on query patterns — use high-cardinality fields that align with read + and write access patterns + rationale: Partition key choice is the single most important Cosmos DB design decision; bad keys cause hot partitions, throttling, + and cross-partition queries + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis +- id: WAF-PERF-DB-003 + severity: required + description: Configure connection pooling for all database connections — exact connection string patterns for SQL, Cosmos, + and PostgreSQL + rationale: Connection creation takes 20-100ms; pooling reuses connections, reducing latency and preventing connection exhaustion + under load + applies_to: + - app-developer + - csharp-developer + - python-developer + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis +- id: WAF-PERF-DB-004 + severity: recommended + description: Configure read replicas for SQL and PostgreSQL to offload read traffic from the primary + rationale: Read replicas handle 50-80% of typical application traffic (reads); offloading reduces primary load and improves + read latency + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis +- id: WAF-PERF-DB-005 + severity: required + description: Enable Query Performance Insight and diagnostic settings for database performance monitoring + rationale: Without query monitoring, slow queries go undetected until they cause user-visible performance degradation + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - monitoring-agent + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Cache/redis +patterns: +- name: Database performance baseline + description: Enable diagnostics on all databases, create indexes for primary queries in deploy.sh, configure connection + pooling, and set up read replicas for production +anti_patterns: +- description: Do not use SELECT * in application queries + instead: Select only required columns and use covering indexes with INCLUDE +- description: Do not use cross-partition queries in Cosmos DB for common operations + instead: Design partition keys to align with primary query patterns; use point reads where possible +- description: Do not create database connections in a loop + instead: Use connection pooling with Min/Max Pool Size configured in the connection string +- description: Do not skip indexing for known query patterns + instead: Create nonclustered indexes with INCLUDE columns for all primary query patterns in deploy.sh +references: +- title: SQL Database performance monitoring + url: https://learn.microsoft.com/azure/azure-sql/database/monitor-tune-overview +- title: Cosmos DB partition key design + url: https://learn.microsoft.com/azure/cosmos-db/partitioning-overview +- title: PostgreSQL performance tuning + url: https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-query-performance-insight +- title: SQL indexing best practices + url: https://learn.microsoft.com/sql/relational-databases/indexes/indexes +- title: Azure SQL read scale-out + url: https://learn.microsoft.com/azure/azure-sql/database/read-scale-out diff --git a/azext_prototype/governance/policies/performance/networking.policy.yaml b/azext_prototype/governance/policies/performance/networking.policy.yaml new file mode 100644 index 0000000..2d5309c --- /dev/null +++ b/azext_prototype/governance/policies/performance/networking.policy.yaml @@ -0,0 +1,145 @@ +kind: policy +domain: performance +description: Governance policies for Networking Optimization +last_updated: '2026-03-27' +rules: +- id: WAF-PERF-NET-001 + severity: required + description: Serve static content through CDN or Front Door — configure origin groups, caching, and compression for optimal + delivery + rationale: Serving static content from origin adds 50-200ms latency per request; CDN/Front Door reduces this to <10ms from + edge POPs globally + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Network/trafficManagerProfiles + - Microsoft.Compute/virtualMachines + - Microsoft.Network/loadBalancers + - Microsoft.Network/virtualNetworks + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Network/expressRouteCircuits +- id: WAF-PERF-NET-002 + severity: recommended + description: Configure connection keep-alive and HTTP/2 for App Service and API Management to reduce connection overhead + rationale: Each new TCP+TLS connection adds 50-150ms overhead; keep-alive reuses connections and HTTP/2 multiplexes requests + on a single connection + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Network/trafficManagerProfiles + - Microsoft.Compute/virtualMachines + - Microsoft.Network/loadBalancers + - Microsoft.Network/virtualNetworks + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Network/expressRouteCircuits +- id: WAF-PERF-NET-003 + severity: recommended + description: Configure multi-region deployment with Traffic Manager or Front Door for latency-sensitive production workloads + rationale: Single-region deployment adds 50-300ms latency for users in distant regions; multi-region deployment ensures + <50ms latency globally + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Network/trafficManagerProfiles + - Microsoft.Compute/virtualMachines + - Microsoft.Network/loadBalancers + - Microsoft.Network/virtualNetworks + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Network/expressRouteCircuits +- id: WAF-PERF-NET-004 + severity: recommended + description: Enable accelerated networking for production VMs and VMSS to reduce latency and increase throughput + rationale: Accelerated networking bypasses the host virtual switch, reducing latency by 50% and increasing throughput by + 2-5x. Available on D/E/F/M-series VMs + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Network/trafficManagerProfiles + - Microsoft.Compute/virtualMachines + - Microsoft.Network/loadBalancers + - Microsoft.Network/virtualNetworks + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Network/expressRouteCircuits +- id: WAF-PERF-NET-005 + severity: recommended + description: Select ExpressRoute over VPN Gateway for production workloads requiring predictable latency, high throughput, + or private network connectivity + rationale: VPN Gateway traffic traverses the public internet with variable latency; ExpressRoute provides dedicated private + connectivity with guaranteed bandwidth and SLA + applies_to: + - cloud-architect + - cost-analyst + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Network/frontDoors + - Microsoft.Cdn/profiles + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Network/trafficManagerProfiles + - Microsoft.Compute/virtualMachines + - Microsoft.Network/loadBalancers + - Microsoft.Network/virtualNetworks + - Microsoft.Network/virtualNetworkGateways + - Microsoft.Network/expressRouteCircuits +patterns: +- name: Edge-optimized content delivery + description: Front Door/CDN for static content + API routing, with separate origin groups for static (Storage) and dynamic + (App Service) content +- name: Multi-region active-active + description: Traffic Manager Performance routing with health probes for automatic failover to closest healthy region +anti_patterns: +- description: Do not serve static content from application servers + instead: Host static content in Storage Account and serve through Front Door/CDN with edge caching +- description: Do not deploy production applications in a single region + instead: Use multi-region deployment with Traffic Manager or Front Door for latency and availability +- description: Do not use VPN Gateway for latency-sensitive production workloads + instead: Use ExpressRoute for predictable, low-latency private connectivity +- description: Do not skip accelerated networking for production VMs + instead: Enable enableAcceleratedNetworking on all D/E/F/M-series VM NICs +references: +- title: Azure Front Door routing + url: https://learn.microsoft.com/azure/frontdoor/front-door-routing-architecture +- title: Traffic Manager routing methods + url: https://learn.microsoft.com/azure/traffic-manager/traffic-manager-routing-methods +- title: Accelerated Networking + url: https://learn.microsoft.com/azure/virtual-network/accelerated-networking-overview +- title: ExpressRoute overview + url: https://learn.microsoft.com/azure/expressroute/expressroute-introduction +- title: Multi-region web application + url: https://learn.microsoft.com/azure/architecture/reference-architectures/app-service-web-app/multi-region diff --git a/azext_prototype/governance/policies/policy.schema.json b/azext_prototype/governance/policies/policy.schema.json deleted file mode 100644 index 3b67f02..0000000 --- a/azext_prototype/governance/policies/policy.schema.json +++ /dev/null @@ -1,196 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Governance Policy", - "description": "Schema for .policy.yaml governance files used by azext-prototype agents.", - "type": "object", - "properties": { - "apiVersion": { - "type": "string", - "enum": ["v1"], - "description": "Schema version. Currently only 'v1' is supported." - }, - "kind": { - "type": "string", - "enum": ["policy"], - "description": "Document kind. Must be 'policy'." - }, - "metadata": { - "type": "object", - "description": "Policy metadata.", - "properties": { - "name": { - "type": "string", - "description": "Policy name (e.g. 'container-apps')." - }, - "category": { - "type": "string", - "enum": ["azure", "security", "integration", "cost", "data", "general"], - "description": "Policy category." - }, - "services": { - "type": "array", - "items": { "type": "string" }, - "description": "Azure services this policy applies to." - }, - "last_reviewed": { - "type": "string", - "description": "Date the policy was last reviewed (YYYY-MM-DD)." - } - }, - "required": ["name", "category", "services"], - "additionalProperties": false - }, - "rules": { - "type": "array", - "description": "Governance rules agents must follow.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Unique rule identifier (e.g. 'CA-001')." - }, - "severity": { - "type": "string", - "enum": ["required", "recommended", "optional"], - "description": "Rule severity level." - }, - "description": { - "type": "string", - "description": "What the rule requires." - }, - "rationale": { - "type": "string", - "description": "Why this rule exists." - }, - "applies_to": { - "type": "array", - "items": { "type": "string" }, - "minItems": 1, - "description": "Agent names this rule applies to." - }, - "template_check": { - "type": "object", - "description": "Optional automated compliance check applied to workload templates. Rules without this block are guidance-only.", - "properties": { - "scope": { - "oneOf": [ - { "type": "string" }, - { "type": "array", "items": { "type": "string" } } - ], - "description": "Service types to check (per-service). Only services matching these types are evaluated." - }, - "require_config": { - "oneOf": [ - { "type": "string" }, - { "type": "array", "items": { "type": "string" } } - ], - "description": "Config keys that must be truthy on matching services." - }, - "require_config_value": { - "type": "object", - "description": "Config key-value pairs that must match exactly.", - "additionalProperties": true - }, - "reject_config_value": { - "type": "object", - "description": "Config key-value pairs that must NOT match.", - "additionalProperties": true - }, - "require_service": { - "oneOf": [ - { "type": "string" }, - { "type": "array", "items": { "type": "string" } } - ], - "description": "Service types that must exist in the template (template-level check)." - }, - "when_services_present": { - "oneOf": [ - { "type": "string" }, - { "type": "array", "items": { "type": "string" } } - ], - "description": "Only apply this check when ALL listed service types are present in the template." - }, - "severity": { - "type": "string", - "enum": ["error", "warning"], - "description": "Override violation severity. Defaults to 'error' for required rules, 'warning' for recommended/optional." - }, - "error_message": { - "type": "string", - "description": "Templated error message. Placeholders: {service_name}, {service_type}, {config_key}, {expected_value}, {actual_value}, {rejected_value}, {rule_id}." - } - }, - "additionalProperties": false - } - }, - "required": ["id", "severity", "description", "applies_to"], - "additionalProperties": false - } - }, - "patterns": { - "type": "array", - "description": "Implementation patterns agents should generate.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "Pattern name." - }, - "description": { - "type": "string", - "description": "When to use this pattern." - }, - "example": { - "type": "string", - "description": "Code example." - } - }, - "required": ["name", "description"], - "additionalProperties": false - } - }, - "anti_patterns": { - "type": "array", - "description": "Anti-patterns agents must avoid.", - "items": { - "type": "object", - "properties": { - "description": { - "type": "string", - "description": "What NOT to do." - }, - "instead": { - "type": "string", - "description": "What to do instead." - } - }, - "required": ["description"], - "additionalProperties": false - } - }, - "references": { - "type": "array", - "description": "Documentation references for agents to cite.", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "Document title." - }, - "url": { - "type": "string", - "format": "uri", - "description": "URL to the reference." - } - }, - "required": ["title", "url"], - "additionalProperties": false - } - } - }, - "required": ["metadata", "rules"], - "additionalProperties": false -} diff --git a/azext_prototype/governance/policies/reliability/__init__.py b/azext_prototype/governance/policies/reliability/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/policies/reliability/backup-&-recovery.policy.yaml b/azext_prototype/governance/policies/reliability/backup-&-recovery.policy.yaml new file mode 100644 index 0000000..7b1a822 --- /dev/null +++ b/azext_prototype/governance/policies/reliability/backup-&-recovery.policy.yaml @@ -0,0 +1,6686 @@ +kind: policy +domain: reliability +description: Governance policies for Backup Recovery +last_updated: '2026-03-27' +rules: +- id: WAF-REL-BKP-001 + severity: required + description: Configure automated backup for ALL data services. Every database, storage account, and key vault MUST have + automated backup enabled with retention policies matching the environment tier. SQL Database and PostgreSQL Flexible + have built-in automated backups — configure retention. Cosmos DB has continuous backup mode. Storage accounts use soft + delete and versioning. Key Vault uses soft delete and purge protection. NEVER deploy a data service without backup configuration. + rationale: Data loss is the most severe reliability failure. Automated backups are the last line of defense against accidental + deletion, corruption, ransomware, and application bugs. Manual backups are unreliable because they depend on human discipline. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.Sql/servers/databases + - Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies + - Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Storage/storageAccounts/blobServices + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === SQL Database: Automated backup with retention === + # SQL Database backups are automatic — configure retention and redundancy. + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Geo-redundant backup storage + } + } + } + + # Configure short-term retention (PITR window) + resource "azapi_resource" "sql_backup_short_term" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 14 # 7 days minimum, 35 days maximum + diffBackupIntervalInHours = 12 # Differential backup every 12 hours + } + } + } + + # Configure long-term retention (LTR) + resource "azapi_resource" "sql_backup_long_term" { + type = "Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + weeklyRetention = "P4W" # Keep weekly backups for 4 weeks + monthlyRetention = "P12M" # Keep monthly backups for 12 months + yearlyRetention = "P5Y" # Keep yearly backups for 5 years + weekOfYear = 1 # Yearly backup taken in week 1 + } + } + } + + # === Cosmos DB: Continuous backup === + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" # Continuous7Days or Continuous30Days + } + } + } + } + } + + # === PostgreSQL Flexible: Backup configuration === + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # 7-35 days; use 35 for production + geoRedundantBackup = "Enabled" + } + } + } + } + + # === Storage Account: Soft delete + Versioning === + resource "azapi_resource" "storage_blob_services" { + type = "Microsoft.Storage/storageAccounts/blobServices@2023-05-01" + name = "default" + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + deleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted blobs for 30 days + } + containerDeleteRetentionPolicy = { + enabled = true + days = 30 # Retain deleted containers for 30 days + } + isVersioningEnabled = true # Enable blob versioning + changeFeed = { + enabled = true + retentionInDays = 30 + } + } + } + } + + # === Key Vault: Soft delete + Purge protection === + resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + enableSoftDelete = true # Cannot be disabled once enabled + softDeleteRetentionInDays = 90 # 7-90 days; default 90 + enablePurgeProtection = true # Prevents permanent deletion during retention + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + } + } + } + bicep_pattern: | + // === SQL Database: Automated backup with retention === + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + resource sqlBackupShortTerm 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 14 + diffBackupIntervalInHours: 12 + } + } + + resource sqlBackupLongTerm 'Microsoft.Sql/servers/databases/backupLongTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + weeklyRetention: 'P4W' + monthlyRetention: 'P12M' + yearlyRetention: 'P5Y' + weekOfYear: 1 + } + } + + // === Cosmos DB: Continuous backup === + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous7Days' + } + } + } + } + + // === PostgreSQL Flexible: Backup configuration === + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: Soft delete + Versioning === + resource storageBlobServices 'Microsoft.Storage/storageAccounts/blobServices@2023-05-01' = { + parent: storageAccount + name: 'default' + properties: { + deleteRetentionPolicy: { + enabled: true + days: 30 + } + containerDeleteRetentionPolicy: { + enabled: true + days: 30 + } + isVersioningEnabled: true + changeFeed: { + enabled: true + retentionInDays: 30 + } + } + } + + // === Key Vault: Soft delete + Purge protection === + resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + } + } + prohibitions: + - NEVER deploy a data service without backup configuration — data loss is unrecoverable + - NEVER set SQL backup retention below 7 days for dev or 14 days for production + - NEVER use Periodic backup mode for Cosmos DB — Continuous mode provides sub-second RPO + - NEVER set PostgreSQL backup retention below 7 days for dev or 30 days for production + - NEVER disable blob soft delete or versioning on production storage accounts + - NEVER disable Key Vault purge protection — it prevents permanent secret/key/certificate destruction + - NEVER use LocallyRedundant backup storage for production SQL databases — use Geo for DR +- id: WAF-REL-BKP-002 + severity: required + description: Deploy a Recovery Services vault for VM backups with geo-redundant storage, soft delete, immutability, and + backup policies. Every production VM MUST be protected by a Recovery Services vault. Configure backup policies with daily + backups, weekly/monthly/yearly retention, and cross-region restore capability. + rationale: Recovery Services vault is the central backup management plane for VMs, SQL in VMs, and file shares. Without + vault protection, VM data is lost on disk failure or accidental deletion. GRS ensures backups survive regional disasters. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-11-01 + name: pe-resource + description: 'Private endpoint for Recovery Services vault (groupId: AzureBackup)' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.service.azure.com + description: Private DNS zone privatelink.{region}.backup.windowsazure.com for vault private endpoint + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-udr + description: Diagnostic settings to route vault operation logs and backup health to Log Analytics + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.RecoveryServices/vaults + - Microsoft.RecoveryServices/vaults/backupstorageconfig + - Microsoft.RecoveryServices/vaults/backupPolicies + - Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Recovery Services Vault === + resource "azapi_resource" "recovery_vault" { + type = "Microsoft.RecoveryServices/vaults@2024-04-01" + name = var.recovery_vault_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Disabled" + securitySettings = { + softDeleteSettings = { + softDeleteState = "Enabled" + softDeleteRetentionPeriodInDays = 14 + enhancedSecurityState = "Enabled" + } + immutabilitySettings = { + state = "Unlocked" + } + } + } + } + } + + # Geo-redundant storage config — MUST be set before protecting items + resource "azapi_resource" "vault_storage_config" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true # Enable cross-region restore + } + } + } + + # === VM Backup Policy === + resource "azapi_resource" "vm_backup_policy" { + type = "Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01" + name = "vm-daily-policy" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + backupManagementType = "AzureIaasVM" + instantRpRetentionRangeInDays = 5 + schedulePolicy = { + schedulePolicyType = "SimpleSchedulePolicy" + scheduleRunFrequency = "Daily" + scheduleRunTimes = ["2024-01-01T02:00:00Z"] # 2 AM UTC + } + retentionPolicy = { + retentionPolicyType = "LongTermRetentionPolicy" + dailySchedule = { + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 30 + durationType = "Days" + } + } + weeklySchedule = { + daysOfTheWeek = ["Sunday"] + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Weeks" + } + } + monthlySchedule = { + retentionScheduleFormatType = "Weekly" + retentionScheduleWeekly = { + daysOfTheWeek = ["Sunday"] + weeksOfTheMonth = ["First"] + } + retentionTimes = ["2024-01-01T02:00:00Z"] + retentionDuration = { + count = 12 + durationType = "Months" + } + } + } + timeZone = "UTC" + } + } + } + + # === Protect VM with Backup === + resource "azapi_resource" "vm_backup_protected_item" { + type = "Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01" + name = "VM;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + parent_id = "${azapi_resource.recovery_vault.id}/backupFabrics/Azure/protectionContainers/iaasvmcontainer;iaasvmcontainerv2;${var.resource_group_name};${var.vm_name}" + + body = { + properties = { + protectedItemType = "Microsoft.Compute/virtualMachines" + policyId = azapi_resource.vm_backup_policy.id + sourceResourceId = azapi_resource.virtual_machine.id + } + } + } + bicep_pattern: | + // === Recovery Services Vault === + resource recoveryVault 'Microsoft.RecoveryServices/vaults@2024-04-01' = { + name: recoveryVaultName + location: location + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Standard' + } + properties: { + publicNetworkAccess: 'Disabled' + securitySettings: { + softDeleteSettings: { + softDeleteState: 'Enabled' + softDeleteRetentionPeriodInDays: 14 + enhancedSecurityState: 'Enabled' + } + immutabilitySettings: { + state: 'Unlocked' + } + } + } + } + + resource vaultStorageConfig 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + + // === VM Backup Policy === + resource vmBackupPolicy 'Microsoft.RecoveryServices/vaults/backupPolicies@2024-04-01' = { + parent: recoveryVault + name: 'vm-daily-policy' + properties: { + backupManagementType: 'AzureIaasVM' + instantRpRetentionRangeInDays: 5 + schedulePolicy: { + schedulePolicyType: 'SimpleSchedulePolicy' + scheduleRunFrequency: 'Daily' + scheduleRunTimes: ['2024-01-01T02:00:00Z'] + } + retentionPolicy: { + retentionPolicyType: 'LongTermRetentionPolicy' + dailySchedule: { + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 30 + durationType: 'Days' + } + } + weeklySchedule: { + daysOfTheWeek: ['Sunday'] + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Weeks' + } + } + monthlySchedule: { + retentionScheduleFormatType: 'Weekly' + retentionScheduleWeekly: { + daysOfTheWeek: ['Sunday'] + weeksOfTheMonth: ['First'] + } + retentionTimes: ['2024-01-01T02:00:00Z'] + retentionDuration: { + count: 12 + durationType: 'Months' + } + } + } + timeZone: 'UTC' + } + } + + // === Protect VM with Backup === + resource vmBackupProtectedItem 'Microsoft.RecoveryServices/vaults/backupFabrics/protectionContainers/protectedItems@2024-04-01' = { + name: '${recoveryVault.name}/Azure/iaasvmcontainer;iaasvmcontainerv2;${resourceGroupName};${vmName}/VM;iaasvmcontainerv2;${resourceGroupName};${vmName}' + properties: { + protectedItemType: 'Microsoft.Compute/virtualMachines' + policyId: vmBackupPolicy.id + sourceResourceId: virtualMachine.id + } + } + prohibitions: + - NEVER deploy production VMs without Recovery Services vault backup protection + - NEVER use LocallyRedundant storage for production vault — GRS is required for regional disaster recovery + - NEVER disable soft delete on Recovery Services vault — backup data cannot be recovered after deletion + - NEVER set daily retention below 7 days for dev or 30 days for production + - NEVER configure backup storage redundancy after protecting items — it cannot be changed once items are registered +- id: WAF-REL-BKP-003 + severity: required + description: Configure point-in-time restore (PITR) for all production databases. SQL Database supports PITR within the + short-term retention window (7-35 days). Cosmos DB Continuous backup enables PITR to any second within the retention + period (7 or 30 days). PostgreSQL Flexible supports PITR within the backup retention window (7-35 days). PITR is the + primary recovery mechanism for application bugs, accidental deletes, and data corruption — it is NOT optional. + rationale: PITR enables recovery to the exact moment before a data-corrupting event. Traditional full-backup restore loses + all data since the last backup (hours of RPO). PITR provides near-zero RPO (seconds for Cosmos, minutes for SQL/PostgreSQL). + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === SQL Database: PITR is built-in — configure retention window === + # SQL Database automatically takes full, differential, and log backups. + # PITR recovery is available via Azure Portal, CLI, or ARM API. + # The retentionDays on backupShortTermRetentionPolicies controls the PITR window. + resource "azapi_resource" "sql_pitr_policy" { + type = "Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview" + name = "default" + parent_id = azapi_resource.sql_database.id + + body = { + properties = { + retentionDays = 35 # Maximum PITR window (7-35 days) + diffBackupIntervalInHours = 12 # 12 or 24 hours between differentials + } + } + } + + # === Cosmos DB: Continuous backup for PITR === + # Restore to any point within the continuous backup window. + # Continuous7Days: 7-day window (free with provisioned throughput) + # Continuous30Days: 30-day window (additional cost) + resource "azapi_resource" "cosmos_continuous_backup" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous30Days" # 30-day PITR window for production + } + } + } + } + } + + # === PostgreSQL Flexible: PITR via backup retention === + # PITR is automatic — restore creates a new server at the chosen point. + resource "azapi_resource" "postgresql_pitr_config" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + backupRetentionDays = 35 # Maximum PITR window (7-35 days) + geoRedundantBackup = "Enabled" + } + } + } + } + bicep_pattern: | + // === SQL Database: PITR retention window === + resource sqlPitrPolicy 'Microsoft.Sql/servers/databases/backupShortTermRetentionPolicies@2023-08-01-preview' = { + parent: sqlDatabase + name: 'default' + properties: { + retentionDays: 35 + diffBackupIntervalInHours: 12 + } + } + + // === Cosmos DB: Continuous backup for PITR === + resource cosmosContinuousBackup 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + backupPolicy: { + type: 'Continuous' + continuousModeProperties: { + tier: 'Continuous30Days' + } + } + } + } + + // === PostgreSQL Flexible: PITR via backup retention === + resource postgresqlPitrConfig 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + backupRetentionDays: 35 + geoRedundantBackup: 'Enabled' + } + } + } + prohibitions: + - NEVER set SQL Database PITR retention below 7 days — minimum recovery window must cover a full week + - NEVER use Periodic backup mode for production Cosmos DB — Continuous mode is required for PITR + - NEVER set PostgreSQL backup retention below 7 days — insufficient for detecting and recovering from data corruption + - NEVER assume PITR restores in-place — SQL and PostgreSQL PITR creates a NEW server/database; plan for DNS/connection + string updates +- id: WAF-REL-BKP-004 + severity: required + description: Configure geo-redundant backup storage for all production data services. SQL Database must use Geo backup + storage redundancy. PostgreSQL Flexible must enable geoRedundantBackup. Storage accounts must use GZRS or RA-GZRS for + critical data. Recovery Services vaults must use GeoRedundant storage with cross-region restore enabled. Backup data + must survive a full regional outage. + rationale: Locally-redundant backups are lost in a regional disaster (earthquake, flood, extended power outage). Geo-redundant + backups are replicated to the Azure paired region, ensuring recovery even when the entire primary region is unavailable. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.DBforMySQL/flexibleServers + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.Storage/storageAccounts + - Microsoft.RecoveryServices/vaults/backupstorageconfig + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.KeyVault/vaults + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.RecoveryServices/vaults + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.DataProtection/backupVaults + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === SQL Database: Geo-redundant backup storage === + resource "azapi_resource" "sql_database_geo_backup" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + properties = { + requestedBackupStorageRedundancy = "Geo" # Options: Local, Zone, Geo, GeoZone + } + } + } + + # === PostgreSQL Flexible: Geo-redundant backup === + resource "azapi_resource" "postgresql_geo_backup" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + backup = { + geoRedundantBackup = "Enabled" # Replicate backups to paired region + } + } + } + } + + # === Storage Account: Geo-Zone-Redundant (GZRS) === + resource "azapi_resource" "storage_gzrs" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_GZRS" # Geo-zone-redundant: 3 zones + paired region + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + } + + # === Recovery Services Vault: GRS with cross-region restore === + resource "azapi_resource" "vault_geo_storage" { + type = "Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01" + name = "vaultstorageconfig" + parent_id = azapi_resource.recovery_vault.id + + body = { + properties = { + storageModelType = "GeoRedundant" + crossRegionRestoreFlag = true + } + } + } + bicep_pattern: | + // === SQL Database: Geo-redundant backup storage === + resource sqlDatabaseGeoBackup 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + properties: { + requestedBackupStorageRedundancy: 'Geo' + } + } + + // === PostgreSQL Flexible: Geo-redundant backup === + resource postgresqlGeoBackup 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + properties: { + backup: { + geoRedundantBackup: 'Enabled' + } + } + } + + // === Storage Account: GZRS === + resource storageGzrs 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_GZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + } + + // === Recovery Services Vault: GRS with cross-region restore === + resource vaultGeoStorage 'Microsoft.RecoveryServices/vaults/backupstorageconfig@2024-04-01' = { + parent: recoveryVault + name: 'vaultstorageconfig' + properties: { + storageModelType: 'GeoRedundant' + crossRegionRestoreFlag: true + } + } + prohibitions: + - NEVER use Local or Zone backup storage redundancy for production SQL databases — regional failure causes backup loss + - NEVER disable geo-redundant backup for production PostgreSQL Flexible servers + - NEVER use Standard_LRS or Standard_ZRS for production storage containing critical data — use Standard_GZRS or Standard_RAGZRS + - NEVER use LocallyRedundant storage for production Recovery Services vaults + - NEVER disable cross-region restore on geo-redundant Recovery Services vaults — it is needed for regional DR +- id: WAF-REL-BKP-005 + severity: recommended + description: Implement backup verification and restore testing automation. Deploy Azure Automation runbooks or Logic Apps + that periodically validate backup health, test restores to a staging environment, and alert on backup failures. Backup + without tested restores is a false sense of security. Use Recovery Services vault backup reports and Azure Monitor alerts + to track backup health. + rationale: Untested backups frequently fail at restore time due to corruption, missing dependencies, or configuration drift. Regular + restore testing proves recoverability and measures actual RTO. Backup health monitoring catches failures before they + become critical. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Insights/actionGroups@2023-01-01 + name: ag-ops + description: Action group for backup failure notifications (email, SMS, webhook) + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-resource + description: Diagnostic settings on Recovery Services vault to send backup logs to Log Analytics + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.Insights/scheduledQueryRules + - Microsoft.KeyVault/vaults + - Microsoft.RecoveryServices/vaults + - Microsoft.DataProtection/backupVaults + - Microsoft.ContainerService/managedClusters + - Microsoft.Compute/virtualMachines +anti_patterns: +- description: Deploying databases without any backup configuration + instead: Configure automated backups with retention matching environment tier (7+ days dev, 30+ days prod) +- description: Using locally-redundant backup storage for production workloads + instead: Use geo-redundant backup storage (GRS) for Recovery Services vaults and SQL databases +- description: Deploying VMs without Recovery Services vault protection + instead: Protect every production VM with a Recovery Services vault backup policy +- description: Setting backup retention to the minimum without business justification + instead: Set retention based on recovery requirements — 14+ days short-term, 12+ months long-term for production +- description: Using Cosmos DB Periodic backup mode for production + instead: Use Continuous backup mode for near-zero RPO and point-in-time restore capability +- description: Disabling Key Vault purge protection + instead: Always enable purge protection — it prevents permanent destruction of secrets, keys, and certificates +references: +- title: Azure Well-Architected Framework — Design for recovery + url: https://learn.microsoft.com/azure/well-architected/reliability/recovery-design +- title: SQL Database automated backups + url: https://learn.microsoft.com/azure/azure-sql/database/automated-backups-overview +- title: Cosmos DB continuous backup + url: https://learn.microsoft.com/azure/cosmos-db/continuous-backup-restore-introduction +- title: Recovery Services vault overview + url: https://learn.microsoft.com/azure/backup/backup-azure-recovery-services-vault-overview +- title: PostgreSQL Flexible backup and restore + url: https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-backup-restore diff --git a/azext_prototype/governance/policies/reliability/deployment-safety.policy.yaml b/azext_prototype/governance/policies/reliability/deployment-safety.policy.yaml new file mode 100644 index 0000000..a266651 --- /dev/null +++ b/azext_prototype/governance/policies/reliability/deployment-safety.policy.yaml @@ -0,0 +1,246 @@ +kind: policy +domain: reliability +description: Governance policies for Deployment Safety +last_updated: '2026-03-27' +rules: +- id: WAF-REL-DEPLOY-001 + severity: required + description: Implement blue-green or canary deployment for ALL production services. App Service MUST use deployment slots + (staging slot with auto-swap or manual swap). Container Apps MUST use revision- based traffic splitting (route percentage + of traffic to new revision). AKS MUST use rolling update strategy with max surge and max unavailable. Functions MUST + use deployment slots for premium/dedicated plans. NEVER deploy directly to production without a staging phase. + rationale: 'Direct-to-production deployments are the #1 cause of production incidents. Blue-green deployment enables zero-downtime + releases with instant rollback. Canary deployment validates changes with a subset of traffic before full rollout. Without + staging, a bad deploy takes down 100% of users immediately.' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Web/sites/slots@2023-12-01 + name: app + description: Staging deployment slot for App Service blue-green deployment + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-resource + description: Diagnostic settings for deployment slot swap events and health check logs + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets +- id: WAF-REL-DEPLOY-002 + severity: required + description: Validate application health BEFORE shifting production traffic to a new deployment. App Service slots MUST + pass health check validation before swap. Container Apps canary revisions MUST pass readiness probes before receiving + traffic. AKS deployments MUST have readiness probes that validate application health including downstream dependencies. Health + validation MUST check database connectivity, cache availability, and external API reachability — not just HTTP 200 from + the root endpoint. + rationale: Deploying code that passes build/test but fails at runtime (wrong connection strings, missing config, incompatible + schema) is a common failure mode. Health gates catch these failures before they affect users. Without gates, the first + sign of failure is user-facing errors. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets +- id: WAF-REL-DEPLOY-003 + severity: required + description: Ensure every production deployment has a tested rollback path. App Service MUST be able to swap back to the + previous slot. Container Apps MUST be able to shift 100% traffic back to the previous revision. AKS MUST have previous + deployment revision history preserved. Container Registry MUST retain previous image versions. Terraform state MUST + be stored remotely with versioning to enable state rollback. Rollback MUST be executable within 5 minutes. + rationale: Rollback is the emergency brake for deployments. If a deployment causes issues that health checks miss (performance + degradation, data corruption, business logic bugs), rollback is the only way to restore service quickly. Without rollback, + the only option is a forward fix under pressure. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ContainerRegistry/registries@2023-07-01 + name: acr + description: Container Registry with retention policy for image version history + - type: Microsoft.Storage/storageAccounts@2023-05-01 + name: st-data + description: Storage account with versioning for Terraform state rollback + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: Storage Blob Data Contributor + description: RBAC for state storage — Storage Blob Data Contributor for deployment identity + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets +- id: WAF-REL-DEPLOY-004 + severity: required + description: ALL infrastructure MUST be defined as code (Terraform or Bicep). NEVER make manual changes to production infrastructure + — all changes must go through the IaC pipeline. Terraform state MUST be stored in a remote backend (Azure Storage) with + locking (Azure Blob lease). Enable drift detection to identify manual changes. Use separate state files per environment + (dev, staging, production) to isolate blast radius. + rationale: Manual infrastructure changes are untraceable, unreproducible, and un-reviewable. IaC provides version control, + peer review, audit trail, and reproducible environments. Remote state with locking prevents concurrent modifications + that corrupt state. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets +- id: WAF-REL-DEPLOY-005 + severity: required + description: Use immutable infrastructure patterns for ALL containerized workloads. Container images MUST be versioned + with unique tags (git SHA, build number, or semantic version) — NEVER use mutable tags like 'latest'. Images MUST be + built once and promoted through environments (dev -> staging -> production) without rebuilding. NEVER modify running + containers in place — deploy new immutable images. ACR MUST have content trust and image quarantine for production images. + rationale: Mutable infrastructure (in-place updates, SSH patches, config changes on running servers) causes configuration + drift, makes debugging impossible, and prevents reliable rollback. Immutable infrastructure ensures every deployment + is reproducible and traceable to a specific build artifact. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ContainerRegistry/registries@2023-07-01 + name: acr + description: Container Registry with Premium SKU for content trust, quarantine, and retention policies + - type: Microsoft.Authorization/roleAssignments@2022-04-01 + name: role-assignment + description: AcrPush role for CI/CD identity, AcrPull role for application identity + - type: Microsoft.Network/privateEndpoints@2023-11-01 + name: pe-resource + description: 'Private endpoint for Container Registry (groupId: registry)' + targets: + - services: + - Microsoft.Web/sites + - Microsoft.App/containerApps + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets +patterns: +- name: Slot swap deployment script + description: Deploy to staging slot, validate health, swap to production, and provide rollback capability in a single deploy.sh + script. + example: | + #!/bin/bash + set -euo pipefail + + RESOURCE_GROUP="${RESOURCE_GROUP}" + APP_NAME="${APP_NAME}" + STAGING_URL="https://${APP_NAME}-staging.azurewebsites.net" + + # 1. Deploy to staging slot + echo "Deploying to staging slot..." + az webapp deploy -g "$RESOURCE_GROUP" -n "$APP_NAME" -s staging \ + --src-path ./dist/app.zip --type zip + + # 2. Warm up staging slot + echo "Warming up staging..." + curl -s -o /dev/null "${STAGING_URL}/healthz" || true + sleep 10 + + # 3. Validate health + echo "Validating staging health..." + STATUS=$(curl -s -o /dev/null -w "%{http_code}" "${STAGING_URL}/healthz") + if [ "$STATUS" != "200" ]; then + echo "ERROR: Staging health check failed (HTTP $STATUS). Aborting." + exit 1 + fi + + # 4. Swap to production + echo "Swapping staging to production..." + az webapp deployment slot swap -g "$RESOURCE_GROUP" -n "$APP_NAME" \ + -s staging --target-slot production + + echo "Deployment complete. To rollback: swap staging back to production." +- name: Container Apps canary deployment script + description: Deploy a new Container App revision with canary traffic splitting, validate, then shift all traffic. + example: | + #!/bin/bash + set -euo pipefail + + RESOURCE_GROUP="${RESOURCE_GROUP}" + APP_NAME="${APP_NAME}" + IMAGE="${ACR_NAME}.azurecr.io/${IMAGE_NAME}:${IMAGE_TAG}" + + # 1. Deploy new revision (receives 0% traffic initially) + echo "Deploying new revision..." + az containerapp update -g "$RESOURCE_GROUP" -n "$APP_NAME" \ + --image "$IMAGE" --revision-suffix "${IMAGE_TAG}" + + NEW_REVISION="${APP_NAME}--${IMAGE_TAG}" + + # 2. Send 10% canary traffic + echo "Routing 10% canary traffic to ${NEW_REVISION}..." + STABLE=$(az containerapp revision list -g "$RESOURCE_GROUP" -n "$APP_NAME" \ + --query "[?properties.active && name!='${NEW_REVISION}'].name | [0]" -o tsv) + az containerapp ingress traffic set -g "$RESOURCE_GROUP" -n "$APP_NAME" \ + --revision-weight "${STABLE}=90" "${NEW_REVISION}=10" + + # 3. Monitor canary (check error rate, latency) + echo "Monitoring canary for 5 minutes..." + sleep 300 + + # 4. Promote to 100% + echo "Promoting ${NEW_REVISION} to 100% traffic..." + az containerapp ingress traffic set -g "$RESOURCE_GROUP" -n "$APP_NAME" \ + --revision-weight "${NEW_REVISION}=100" + + echo "Deployment complete." +anti_patterns: +- description: Deploying directly to production without a staging phase + instead: Use deployment slots (App Service), revision traffic splitting (Container Apps), or rolling updates (AKS) +- description: Using mutable image tags like 'latest' in production + instead: Tag images with immutable identifiers (git SHA, build number, semantic version) +- description: Making manual changes to production infrastructure + instead: Define all infrastructure as code and apply changes through CI/CD pipelines +- description: Storing Terraform state locally + instead: Use Azure Storage remote backend with versioning, locking, and Entra ID authentication +- description: Deploying without rollback capability + instead: Ensure every deployment has a tested rollback path executable within 5 minutes +- description: Rebuilding container images for each environment + instead: Build once, promote the same image artifact through dev, staging, production +references: +- title: Azure Well-Architected Framework — Keep it simple + url: https://learn.microsoft.com/azure/well-architected/reliability/simplify +- title: App Service deployment slots + url: https://learn.microsoft.com/azure/app-service/deploy-staging-slots +- title: Container Apps traffic splitting + url: https://learn.microsoft.com/azure/container-apps/traffic-splitting +- title: Terraform remote state in Azure + url: https://learn.microsoft.com/azure/developer/terraform/store-state-in-azure-storage +- title: Immutable infrastructure pattern + url: https://learn.microsoft.com/azure/architecture/guide/design-principles/immutable-infrastructure +- title: Blue-green deployment pattern + url: https://learn.microsoft.com/azure/architecture/example-scenario/blue-green-spring/blue-green-spring diff --git a/azext_prototype/governance/policies/reliability/fault-tolerance.policy.yaml b/azext_prototype/governance/policies/reliability/fault-tolerance.policy.yaml new file mode 100644 index 0000000..a62e508 --- /dev/null +++ b/azext_prototype/governance/policies/reliability/fault-tolerance.policy.yaml @@ -0,0 +1,243 @@ +kind: policy +domain: reliability +description: Governance policies for Fault Tolerance +last_updated: '2026-03-27' +rules: +- id: WAF-REL-FT-001 + severity: required + description: 'Implement the circuit breaker pattern for ALL external service calls. Circuit breakers prevent cascading failures + by stopping calls to a failing dependency after a threshold of consecutive errors. Use Dapr resiliency policies for Container + Apps, Polly for .NET applications, resilience4j for Java, and APIM circuit breaker policy for API gateway-level protection. Every + circuit breaker MUST define: failure threshold, open duration (timeout), and half-open probe count.' + rationale: Without circuit breakers, a single failing dependency causes all callers to block on timeout, exhausting connection + pools and thread pools, which cascades failure to the entire system. Circuit breakers fail fast, preserve resources, + and allow recovery. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.Network/loadBalancers + - Microsoft.Network/applicationGateways +- id: WAF-REL-FT-002 + severity: required + description: Configure retry policies with exponential backoff and jitter for ALL external service calls. Azure SDK clients + have built-in retry policies — configure them explicitly rather than relying on defaults. For custom HTTP calls, implement + exponential backoff with jitter to avoid thundering herd effects. Maximum retry count MUST be bounded (3-5 retries). Base + delay MUST start at 1-2 seconds. Jitter MUST be added to prevent synchronized retries. + rationale: Transient failures (network glitches, throttling, brief service restarts) are inevitable in distributed systems. Without + retry, every transient failure becomes a user-visible error. Without backoff, rapid retries overwhelm the recovering + service. Without jitter, synchronized retries from multiple clients create load spikes. + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.Network/loadBalancers + - Microsoft.Network/applicationGateways +- id: WAF-REL-FT-003 + severity: required + description: Implement bulkhead isolation to prevent a single failing component from consuming all system resources. Container + Apps and AKS MUST have resource limits (CPU/memory) per container. AKS MUST have Pod Disruption Budgets (PDBs) to ensure + minimum availability during voluntary disruptions. Thread pools and connection pools MUST be bounded. Separate critical + and non-critical workloads into different compute instances. + rationale: Without bulkhead isolation, a single runaway process can consume all CPU/memory, starving healthy workloads. Connection + pool exhaustion from one dependency blocks all other outbound calls. PDBs prevent Kubernetes evictions from violating + availability requirements. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.Network/loadBalancers + - Microsoft.Network/applicationGateways +- id: WAF-REL-FT-004 + severity: recommended + description: Implement graceful degradation patterns so that partial failures do not cause total service unavailability. Use + feature flags to disable non-critical features when dependencies fail. Configure fallback endpoints and cached responses. Implement + degraded mode that serves stale data or reduced functionality rather than returning errors. Azure App Configuration with + feature filters provides centralized feature flag management. + rationale: Users prefer a degraded experience over a complete outage. If the recommendation engine fails, the e-commerce + site should still show products without recommendations — not return a 500 error. Feature flags enable instant degradation + without redeployment. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.Network/privateEndpoints@2023-11-01 + name: pe-resource + description: 'Private endpoint for App Configuration (groupId: configurationStores)' + - type: Microsoft.Network/privateDnsZones@2020-06-01 + name: privatelink.azconfig.io + description: Private DNS zone privatelink.azconfig.io for App Configuration private endpoint + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-resource + description: Diagnostic settings for App Configuration audit and request logs + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.Network/loadBalancers + - Microsoft.Network/applicationGateways +- id: WAF-REL-FT-005 + severity: required + description: Use queue-based load leveling for all workloads with variable or bursty traffic patterns. Place Service Bus + queues or Event Hubs between producers and consumers to absorb traffic spikes and decouple processing rate from arrival + rate. Service Bus Premium tier provides zone redundancy, large message support, and FIFO ordering. Event Hubs is for + high-throughput streaming (millions of events/sec). NEVER process high-volume workloads synchronously without a buffer. + rationale: Synchronous processing of bursty traffic causes cascading failures when arrival rate exceeds processing capacity. Queues + absorb spikes, enable independent scaling of producers and consumers, and provide at-least-once delivery guarantees. Without + queues, every traffic spike risks service overload and data loss. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + companion_resources: + - type: Microsoft.ServiceBus/namespaces/queues@2024-01-01 + name: sb-namespace + description: Dead-letter queue (automatic sub-queue) — monitor for poison messages + - type: Microsoft.Network/privateEndpoints@2023-11-01 + name: pe-resource + description: Private endpoint for Service Bus / Event Hub namespace + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-metrics + description: Diagnostic settings for queue depth, dead-letter count, and throughput metrics + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ContainerService/managedClusters + - Microsoft.ApiManagement/service + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Sql/servers/databases + - Microsoft.Network/loadBalancers + - Microsoft.Network/applicationGateways +patterns: +- name: Circuit breaker with retry composition + description: 'Compose circuit breaker and retry policies correctly: retry wraps the circuit breaker, so transient failures + are retried but sustained failures trip the circuit.' + example: | + // .NET: Correct composition order + builder.Services.AddHttpClient("api") + .AddResilienceHandler("pipeline", builder => { + builder.AddRetry(new HttpRetryStrategyOptions { + MaxRetryAttempts = 3, + BackoffType = DelayBackoffType.ExponentialWithJitter + }); + builder.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions { + FailureRatio = 0.5, + SamplingDuration = TimeSpan.FromSeconds(30), + BreakDuration = TimeSpan.FromSeconds(15) + }); + builder.AddTimeout(TimeSpan.FromSeconds(10)); + }); +- name: Competing consumers pattern + description: Scale consumers independently from producers using queue-based load leveling. Multiple consumers process from + the same queue concurrently, each handling one message at a time. + example: | + // Container Apps: Scale consumers based on queue depth + // Use KEDA Service Bus scaler + resource containerAppConsumer 'Microsoft.App/containerApps@2024-03-01' = { + properties: { + template: { + scale: { + minReplicas: 1 + maxReplicas: 10 + rules: [ + { + name: 'queue-scaling' + custom: { + type: 'azure-servicebus' + metadata: { + queueName: 'orders' + namespace: serviceBusNamespace.name + messageCount: '5' // Scale when 5+ messages per replica + } + identity: userAssignedIdentity.id + } + } + ] + } + } + } + } +anti_patterns: +- description: Making synchronous calls to external services without timeout or circuit breaker + instead: Wrap all external calls with circuit breaker + retry + timeout using Polly, resilience4j, or Dapr +- description: Deploying containers without CPU and memory resource limits + instead: Set explicit CPU and memory limits on every container to prevent resource starvation +- description: Processing bursty workloads synchronously without a message queue + instead: Use Service Bus or Event Hub as a buffer between producers and consumers +- description: Hardcoding feature flags in application code + instead: Use Azure App Configuration for centralized feature flag management with instant toggle capability +- description: Using Service Bus connection strings instead of managed identity + instead: 'Disable local auth (disableLocalAuth: true) and use RBAC with managed identity' +- description: Deploying AKS workloads without Pod Disruption Budgets + instead: Create PDBs with minAvailable or maxUnavailable to protect availability during voluntary disruptions +references: +- title: Azure Well-Architected Framework — Design for resilience + url: https://learn.microsoft.com/azure/well-architected/reliability/design-resiliency +- title: Circuit breaker pattern + url: https://learn.microsoft.com/azure/architecture/patterns/circuit-breaker +- title: Retry pattern with exponential backoff + url: https://learn.microsoft.com/azure/architecture/patterns/retry +- title: Bulkhead pattern + url: https://learn.microsoft.com/azure/architecture/patterns/bulkhead +- title: Queue-based load leveling pattern + url: https://learn.microsoft.com/azure/architecture/patterns/queue-based-load-leveling +- title: Graceful degradation pattern + url: https://learn.microsoft.com/azure/architecture/patterns/graceful-degradation diff --git a/azext_prototype/governance/policies/reliability/high-availability.policy.yaml b/azext_prototype/governance/policies/reliability/high-availability.policy.yaml new file mode 100644 index 0000000..26ecbd1 --- /dev/null +++ b/azext_prototype/governance/policies/reliability/high-availability.policy.yaml @@ -0,0 +1,16685 @@ +kind: policy +domain: reliability +description: Governance policies for High Availability +last_updated: '2026-03-27' +rules: +- id: WAF-REL-HA-001 + severity: recommended + description: 'Enable zone redundancy for ALL production PaaS services. Every service that supports availability zones MUST + be configured with zone-redundant deployment. This is the single most impactful reliability control — it protects against + datacenter-level failures with zero application changes. Configure the exact zone properties per service type: zoneRedundant + for Container Apps and Service Bus Premium; zones for AKS node pools, VMs, and Public IPs; ZRS replication for Storage; + zone-redundant HA for SQL and PostgreSQL Flexible; multi-AZ writes for Cosmos DB; zone redundancy for Redis Enterprise.' + rationale: Azure availability zones are physically separated datacenters within a region. Zone-redundant deployments survive + a full datacenter failure (power, cooling, networking). Without zone redundancy, a single datacenter outage takes down + the entire service. Azure SLA improves from 99.9% to 99.95%-99.99% with zone redundancy. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + template_check: + scope: + - sql-database + - cosmos-db + - storage + - container-apps + - aks + - redis-cache + - service-bus + - postgresql-flexible + require_config: + - zone_redundant + error_message: Service '{service_name}' ({service_type}) must configure zone_redundant for production reliability + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.ContainerService/managedClusters + - Microsoft.App/managedEnvironments + - Microsoft.Cache/redis + - Microsoft.ServiceBus/namespaces + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Zone Redundancy per Service Type (azapi_resource) === + # EVERY production PaaS resource MUST include zone configuration. + + # --- SQL Database: Zone-redundant HA --- + resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.sql_database_name + parent_id = azapi_resource.sql_server.id + location = var.location + + body = { + sku = { + name = "GP_Gen5" + tier = "GeneralPurpose" + capacity = 2 + } + properties = { + zoneRedundant = true # Zone-redundant HA for General Purpose / Business Critical + maxSizeBytes = 34359738368 # 32 GB + } + } + } + + # --- Cosmos DB: Multi-AZ (zone redundancy per region) --- + resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + databaseAccountOfferType = "Standard" + locations = [ + { + locationName = var.location + failoverPriority = 0 + isZoneRedundant = true # Enable availability zones for this region + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + } + } + } + + # --- Storage Account: Zone-Redundant Storage (ZRS) --- + resource "azapi_resource" "storage_account" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_ZRS" # Zone-Redundant Storage — 3 copies across 3 zones + } + kind = "StorageV2" + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + allowBlobPublicAccess = false + } + } + } + + # --- AKS: Zone-spanning node pools --- + resource "azapi_resource" "aks_cluster" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.aks_cluster_name + parent_id = azapi_resource.resource_group.id + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + agentPoolProfiles = [ + { + name = "system" + mode = "System" + count = 3 + vmSize = "Standard_D2s_v5" + osType = "Linux" + availabilityZones = ["1", "2", "3"] # Spread across all 3 zones + enableAutoScaling = true + minCount = 3 + maxCount = 9 + } + ] + } + } + } + + # --- Container Apps Environment: Zone redundancy --- + resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.container_app_env_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + zoneRedundant = true # Replicas distributed across availability zones + vnetConfiguration = { + infrastructureSubnetId = var.container_app_subnet_id + internal = true + } + } + } + } + + # --- Redis Cache: Zone redundancy (Premium tier required) --- + resource "azapi_resource" "redis_cache" { + type = "Microsoft.Cache/redis@2024-03-01" + name = var.redis_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + sku = { + name = "Premium" + family = "P" + capacity = 1 + } + replicasPerPrimary = 1 + zones = ["1", "2", "3"] # Distribute replicas across zones + enableNonSslPort = false + minimumTlsVersion = "1.2" + } + } + } + + # --- Service Bus: Zone redundancy (Premium tier, automatic) --- + resource "azapi_resource" "service_bus" { + type = "Microsoft.ServiceBus/namespaces@2024-01-01" + name = var.service_bus_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Premium" + tier = "Premium" + capacity = 1 + } + properties = { + zoneRedundant = true # Premium tier supports zone redundancy + minimumTlsVersion = "1.2" + publicNetworkAccess = "Disabled" + disableLocalAuth = true + } + } + } + + # --- PostgreSQL Flexible: Zone-redundant HA --- + resource "azapi_resource" "postgresql_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = "Standard_D2ds_v5" + tier = "GeneralPurpose" + } + properties = { + version = "16" + highAvailability = { + mode = "ZoneRedundant" # Standby in different zone + standbyAvailabilityZone = "2" + } + availabilityZone = "1" + storage = { + storageSizeGB = 128 + } + } + } + } + bicep_pattern: | + // === Zone Redundancy per Service Type (Bicep) === + + // --- SQL Database: Zone-redundant HA --- + resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: sqlDatabaseName + location: location + sku: { + name: 'GP_Gen5' + tier: 'GeneralPurpose' + capacity: 2 + } + properties: { + zoneRedundant: true + maxSizeBytes: 34359738368 + } + } + + // --- Cosmos DB: Multi-AZ --- + resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + properties: { + databaseAccountOfferType: 'Standard' + locations: [ + { + locationName: location + failoverPriority: 0 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + } + } + + // --- Storage Account: ZRS --- + resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + sku: { + name: 'Standard_ZRS' + } + kind: 'StorageV2' + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + allowBlobPublicAccess: false + } + } + + // --- AKS: Zone-spanning node pools --- + resource aksCluster 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: aksClusterName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + agentPoolProfiles: [ + { + name: 'system' + mode: 'System' + count: 3 + vmSize: 'Standard_D2s_v5' + osType: 'Linux' + availabilityZones: ['1', '2', '3'] + enableAutoScaling: true + minCount: 3 + maxCount: 9 + } + ] + } + } + + // --- Container Apps Environment: Zone redundancy --- + resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: containerAppEnvName + location: location + properties: { + zoneRedundant: true + vnetConfiguration: { + infrastructureSubnetId: containerAppSubnetId + internal: true + } + } + } + + // --- Redis Cache: Zone redundancy (Premium) --- + resource redisCache 'Microsoft.Cache/redis@2024-03-01' = { + name: redisName + location: location + properties: { + sku: { + name: 'Premium' + family: 'P' + capacity: 1 + } + replicasPerPrimary: 1 + zones: ['1', '2', '3'] + enableNonSslPort: false + minimumTlsVersion: '1.2' + } + } + + // --- Service Bus: Zone redundancy (Premium) --- + resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = { + name: serviceBusName + location: location + sku: { + name: 'Premium' + tier: 'Premium' + capacity: 1 + } + properties: { + zoneRedundant: true + minimumTlsVersion: '1.2' + publicNetworkAccess: 'Disabled' + disableLocalAuth: true + } + } + + // --- PostgreSQL Flexible: Zone-redundant HA --- + resource postgresqlFlexible 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlName + location: location + sku: { + name: 'Standard_D2ds_v5' + tier: 'GeneralPurpose' + } + properties: { + version: '16' + highAvailability: { + mode: 'ZoneRedundant' + standbyAvailabilityZone: '2' + } + availabilityZone: '1' + storage: { + storageSizeGB: 128 + } + } + } + prohibitions: + - NEVER deploy production PaaS services without zone redundancy — a single datacenter failure will cause a full outage + - NEVER use Standard_LRS for production storage accounts — use Standard_ZRS or Standard_GZRS + - NEVER deploy AKS node pools without availabilityZones — nodes concentrated in one datacenter are a SPOF + - NEVER use Basic/Standard tier Redis in production — only Premium tier supports zone redundancy + - NEVER deploy Service Bus Standard tier for production — Premium tier is required for zone redundancy + - NEVER set PostgreSQL Flexible highAvailability.mode to SameZone for production — use ZoneRedundant + - NEVER omit zoneRedundant on Container Apps Environment for production workloads + - NEVER deploy SQL Database without zoneRedundant = true for General Purpose or Business Critical tiers +- id: WAF-REL-HA-002 + severity: recommended + description: Deploy critical workloads across multiple Azure regions using Azure Front Door or Traffic Manager for active-active + or active-passive failover. Front Door is preferred for HTTP workloads (global load balancing with WAF, SSL offload, + and sub-second failover). Traffic Manager is for non-HTTP protocols (DNS-based routing, 30-60s failover). Each region + must be independently deployable with its own data tier. + rationale: Multi-region deployment protects against region-wide outages (natural disasters, regional Azure incidents). Azure + SLA for multi-region architectures can reach 99.99%+. Without multi- region, a regional outage causes complete service + unavailability. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Cdn/profiles/securityPolicies@2024-02-01 + name: waf-security-policy + description: WAF policy attached to Front Door endpoint for DDoS and bot protection + - type: Microsoft.Network/privateLinkServices@2023-11-01 + name: pls-origin + description: Private Link service for Front Door to origin connectivity (Private Link origin) + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-frontdoor + description: Diagnostic settings for Front Door access logs and health probe logs + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Cdn/profiles + - Microsoft.Cdn/profiles/afdEndpoints + - Microsoft.Cdn/profiles/originGroups + - Microsoft.Cdn/profiles/originGroups/origins + - Microsoft.Cdn/profiles/afdEndpoints/routes + - Microsoft.Network/trafficmanagerprofiles + - Microsoft.Network/trafficmanagerprofiles/azureEndpoints + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Multi-Region Active-Active with Azure Front Door === + + # --- Front Door Profile --- + resource "azapi_resource" "front_door" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.front_door_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + } + } + + # --- Front Door Endpoint --- + resource "azapi_resource" "fd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.fd_endpoint_name + parent_id = azapi_resource.front_door.id + location = "global" + + body = { + properties = { + enabledState = "Enabled" + } + } + } + + # --- Origin Group with health probing --- + resource "azapi_resource" "fd_origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "app-origins" + parent_id = azapi_resource.front_door.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/healthz" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + sessionAffinityState = "Disabled" + } + } + } + + # --- Primary region origin --- + resource "azapi_resource" "fd_origin_primary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.primary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.primary_app_hostname + priority = 1 # Active — receives traffic first + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Secondary region origin --- + resource "azapi_resource" "fd_origin_secondary" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "secondary-region" + parent_id = azapi_resource.fd_origin_group.id + + body = { + properties = { + hostName = var.secondary_app_hostname + httpPort = 80 + httpsPort = 443 + originHostHeader = var.secondary_app_hostname + priority = 1 # Same priority = active-active (use 2 for active-passive) + weight = 1000 + enabledState = "Enabled" + } + } + } + + # --- Route: connect endpoint to origin group --- + resource "azapi_resource" "fd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.fd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.fd_origin_group.id + } + supportedProtocols = ["Https"] + httpsRedirect = "Enabled" + forwardingProtocol = "HttpsOnly" + patternsToMatch = ["/*"] + linkToDefaultDomain = "Enabled" + } + } + } + + # === Multi-Region with Traffic Manager (non-HTTP) === + resource "azapi_resource" "traffic_manager" { + type = "Microsoft.Network/trafficmanagerprofiles@2022-04-01" + name = var.traffic_manager_name + parent_id = azapi_resource.resource_group.id + location = "global" + + body = { + properties = { + profileStatus = "Enabled" + trafficRoutingMethod = "Performance" # Route to closest healthy endpoint + dnsConfig = { + relativeName = var.traffic_manager_dns_name + ttl = 30 + } + monitorConfig = { + protocol = "HTTPS" + port = 443 + path = "/healthz" + intervalInSeconds = 10 + toleratedNumberOfFailures = 3 + timeoutInSeconds = 5 + } + } + } + } + + resource "azapi_resource" "tm_endpoint_primary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "primary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.primary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 1 + } + } + } + + resource "azapi_resource" "tm_endpoint_secondary" { + type = "Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01" + name = "secondary" + parent_id = azapi_resource.traffic_manager.id + + body = { + properties = { + targetResourceId = var.secondary_resource_id + endpointStatus = "Enabled" + weight = 100 + priority = 2 + } + } + } + bicep_pattern: | + // === Multi-Region Active-Active with Azure Front Door === + + resource frontDoor 'Microsoft.Cdn/profiles@2024-02-01' = { + name: frontDoorName + location: 'global' + sku: { + name: 'Premium_AzureFrontDoor' + } + } + + resource fdEndpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: frontDoor + name: fdEndpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } + } + + resource fdOriginGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: frontDoor + name: 'app-origins' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/healthz' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + sessionAffinityState: 'Disabled' + } + } + + resource fdOriginPrimary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'primary-region' + properties: { + hostName: primaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: primaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdOriginSecondary 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: fdOriginGroup + name: 'secondary-region' + properties: { + hostName: secondaryAppHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: secondaryAppHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } + } + + resource fdRoute 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: fdEndpoint + name: 'default-route' + properties: { + originGroup: { + id: fdOriginGroup.id + } + supportedProtocols: ['Https'] + httpsRedirect: 'Enabled' + forwardingProtocol: 'HttpsOnly' + patternsToMatch: ['/*'] + linkToDefaultDomain: 'Enabled' + } + } + + // === Multi-Region with Traffic Manager (non-HTTP) === + resource trafficManager 'Microsoft.Network/trafficmanagerprofiles@2022-04-01' = { + name: trafficManagerName + location: 'global' + properties: { + profileStatus: 'Enabled' + trafficRoutingMethod: 'Performance' + dnsConfig: { + relativeName: trafficManagerDnsName + ttl: 30 + } + monitorConfig: { + protocol: 'HTTPS' + port: 443 + path: '/healthz' + intervalInSeconds: 10 + toleratedNumberOfFailures: 3 + timeoutInSeconds: 5 + } + } + } + + resource tmEndpointPrimary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'primary' + properties: { + targetResourceId: primaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 1 + } + } + + resource tmEndpointSecondary 'Microsoft.Network/trafficmanagerprofiles/azureEndpoints@2022-04-01' = { + parent: trafficManager + name: 'secondary' + properties: { + targetResourceId: secondaryResourceId + endpointStatus: 'Enabled' + weight: 100 + priority: 2 + } + } + prohibitions: + - NEVER use single-region deployment for workloads requiring SLA > 99.9% — multi-region is required + - NEVER use Traffic Manager for HTTP workloads — use Front Door for sub-second failover and WAF integration + - NEVER set both origin priorities to different values for active-active — use same priority with equal weights + - NEVER omit health probe settings on Front Door origin groups — unhealthy origins must be detected automatically + - NEVER use Front Door Standard tier for production — Premium tier is required for Private Link origins and WAF +- id: WAF-REL-HA-003 + severity: required + description: Deploy production VMs and VM Scale Sets across availability zones. Single VMs MUST specify a zones property. VM + Scale Sets MUST use zones = ["1", "2", "3"] with max spreading (platformFaultDomainCount = 1) for optimal zone distribution. Availability + sets are legacy — use zones instead for new deployments. + rationale: VMs without zone placement risk co-location in a single datacenter. Availability zones provide 99.99% SLA vs + 99.95% for availability sets. Zone-redundant VMSS automatically balances instances across zones. + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Compute/virtualMachines + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === VM with Availability Zone Placement === + resource "azapi_resource" "virtual_machine" { + type = "Microsoft.Compute/virtualMachines@2024-03-01" + name = var.vm_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + zones = ["1"] # Pin to specific zone — use 1, 2, or 3 + properties = { + hardwareProfile = { + vmSize = var.vm_size + } + osProfile = { + computerName = var.vm_name + adminUsername = var.admin_username + linuxConfiguration = { + disablePasswordAuthentication = true + ssh = { + publicKeys = [ + { + path = "/home/${var.admin_username}/.ssh/authorized_keys" + keyData = var.ssh_public_key + } + ] + } + } + } + storageProfile = { + osDisk = { + createOption = "FromImage" + managedDisk = { + storageAccountType = "Premium_ZRS" # Zone-redundant managed disk + } + } + imageReference = { + publisher = "Canonical" + offer = "ubuntu-24_04-lts" + sku = "server" + version = "latest" + } + } + networkProfile = { + networkInterfaces = [ + { + id = azapi_resource.nic.id + } + ] + } + } + } + } + + # === VMSS with Zone Spreading === + resource "azapi_resource" "vmss" { + type = "Microsoft.Compute/virtualMachineScaleSets@2024-03-01" + name = var.vmss_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + sku = { + name = var.vm_size + tier = "Standard" + capacity = var.instance_count + } + zones = ["1", "2", "3"] # Spread across all 3 zones + properties = { + orchestrationMode = "Flexible" + platformFaultDomainCount = 1 # Max spreading across zones + singlePlacementGroup = false + upgradePolicy = { + mode = "Rolling" + rollingUpgradePolicy = { + maxBatchInstancePercent = 20 + maxUnhealthyInstancePercent = 20 + maxUnhealthyUpgradedInstancePercent = 5 + pauseTimeBetweenBatches = "PT2S" + } + } + automaticRepairsPolicy = { + enabled = true + gracePeriod = "PT10M" + } + } + } + } + bicep_pattern: | + // === VM with Availability Zone Placement === + resource virtualMachine 'Microsoft.Compute/virtualMachines@2024-03-01' = { + name: vmName + location: location + zones: ['1'] + properties: { + hardwareProfile: { + vmSize: vmSize + } + osProfile: { + computerName: vmName + adminUsername: adminUsername + linuxConfiguration: { + disablePasswordAuthentication: true + ssh: { + publicKeys: [ + { + path: '/home/${adminUsername}/.ssh/authorized_keys' + keyData: sshPublicKey + } + ] + } + } + } + storageProfile: { + osDisk: { + createOption: 'FromImage' + managedDisk: { + storageAccountType: 'Premium_ZRS' + } + } + imageReference: { + publisher: 'Canonical' + offer: 'ubuntu-24_04-lts' + sku: 'server' + version: 'latest' + } + } + networkProfile: { + networkInterfaces: [ + { + id: nic.id + } + ] + } + } + } + + // === VMSS with Zone Spreading === + resource vmss 'Microsoft.Compute/virtualMachineScaleSets@2024-03-01' = { + name: vmssName + location: location + sku: { + name: vmSize + tier: 'Standard' + capacity: instanceCount + } + zones: ['1', '2', '3'] + properties: { + orchestrationMode: 'Flexible' + platformFaultDomainCount: 1 + singlePlacementGroup: false + upgradePolicy: { + mode: 'Rolling' + rollingUpgradePolicy: { + maxBatchInstancePercent: 20 + maxUnhealthyInstancePercent: 20 + maxUnhealthyUpgradedInstancePercent: 5 + pauseTimeBetweenBatches: 'PT2S' + } + } + automaticRepairsPolicy: { + enabled: true + gracePeriod: 'PT10M' + } + } + } + prohibitions: + - NEVER deploy production VMs without specifying zones — VMs without zones may land in any datacenter + - NEVER use Standard_LRS managed disks with zonal VMs — use Premium_ZRS or StandardSSD_ZRS for zone resilience + - NEVER use availability sets for new deployments — availability zones provide superior fault isolation + - NEVER set platformFaultDomainCount > 1 for zone-spanning VMSS — use 1 for max spreading + - NEVER disable automatic repairs on production VMSS — unhealthy instances must be replaced automatically +- id: WAF-REL-HA-004 + severity: required + description: Configure health probes for ALL load-balanced services. Every Load Balancer, Application Gateway, and Front + Door MUST have health probes that check application-level health (not just TCP connectivity). Use HTTP/HTTPS probes with + a dedicated /healthz endpoint that validates downstream dependencies. Probes must have appropriate intervals and thresholds + to balance detection speed with false-positive avoidance. + rationale: Health probes are the foundation of automatic failover. Without application-level health checks, traffic continues + flowing to unhealthy backends. TCP-only probes miss application-level failures (database down, disk full, deadlock). + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Network/loadBalancers/probes + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === Load Balancer Health Probe === + resource "azapi_resource" "lb_probe" { + type = "Microsoft.Network/loadBalancers/probes@2023-11-01" + name = "health-probe" + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + protocol = "Https" + port = 443 + requestPath = "/healthz" + intervalInSeconds = 5 # Check every 5 seconds + numberOfProbes = 2 # Mark unhealthy after 2 consecutive failures + probeThreshold = 2 + } + } + } + + # === Application Gateway Health Probe === + # Health probes are defined inline in Application Gateway properties + resource "azapi_resource" "app_gateway" { + type = "Microsoft.Network/applicationGateways@2023-11-01" + name = var.app_gateway_name + parent_id = azapi_resource.resource_group.id + location = var.location + + body = { + properties = { + probes = [ + { + name = "app-health-probe" + properties = { + protocol = "Https" + host = var.backend_hostname + path = "/healthz" + interval = 10 + timeout = 10 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = false + match = { + statusCodes = ["200-299"] + } + } + } + ] + # Reference probe in backend HTTP settings + backendHttpSettingsCollection = [ + { + name = "app-backend-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + probe = { + id = "${azapi_resource.app_gateway.id}/probes/app-health-probe" + } + } + } + ] + } + } + } + + # === Front Door Health Probe (configured on origin group) === + # See HA-002 for full Front Door pattern — health probes are + # configured in the origin group's healthProbeSettings block: + # healthProbeSettings = { + # probePath = "/healthz" + # probeRequestType = "HEAD" + # probeProtocol = "Https" + # probeIntervalInSeconds = 30 + # } + bicep_pattern: | + // === Load Balancer Health Probe === + resource lbProbe 'Microsoft.Network/loadBalancers/probes@2023-11-01' = { + parent: loadBalancer + name: 'health-probe' + properties: { + protocol: 'Https' + port: 443 + requestPath: '/healthz' + intervalInSeconds: 5 + numberOfProbes: 2 + probeThreshold: 2 + } + } + + // === Application Gateway Health Probe === + resource appGateway 'Microsoft.Network/applicationGateways@2023-11-01' = { + name: appGatewayName + location: location + properties: { + probes: [ + { + name: 'app-health-probe' + properties: { + protocol: 'Https' + host: backendHostname + path: '/healthz' + interval: 10 + timeout: 10 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: false + match: { + statusCodes: ['200-299'] + } + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'app-backend-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + probe: { + id: '${appGateway.id}/probes/app-health-probe' + } + } + } + ] + } + } + + // Front Door health probes: see HA-002 origin group healthProbeSettings + prohibitions: + - NEVER use TCP-only health probes in production — they miss application-level failures (database down, OOM, deadlock) + - NEVER set health probe intervals longer than 30 seconds — slow detection means prolonged traffic to unhealthy backends + - NEVER omit health probes on load-balanced services — traffic will continue flowing to failed backends indefinitely + - NEVER use the root path (/) for health probes — use a dedicated /healthz endpoint that checks downstream dependencies + - NEVER set unhealthyThreshold to 1 — a single failed probe causes premature removal; use 2-3 for stability +- id: WAF-REL-HA-005 + severity: recommended + description: Configure geo-replication for all production databases. SQL Database must have active geo-replication or auto-failover + groups to a paired region. Cosmos DB must have multi-region writes enabled with automatic failover. PostgreSQL Flexible + must have read replicas in a secondary region. Geo-replication provides both read scaling and disaster recovery. + rationale: Geo-replication protects against region-wide outages and reduces read latency for geographically distributed + users. Without geo- replication, a regional outage causes complete data unavailability with potential data loss up to + the last backup (RPO of hours). + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + companion_resources: + - type: Microsoft.Sql/servers@2023-08-01-preview + name: sql-server + description: Secondary SQL Server in paired region for failover group partner + - type: Microsoft.Network/privateEndpoints@2023-11-01 + name: pe-resource + description: Private endpoints for secondary region database servers + - type: Microsoft.Insights/diagnosticSettings@2021-05-01-preview + name: diag-resource + description: Diagnostic settings for replication lag monitoring and failover events + targets: + - services: + - Microsoft.Sql/servers/databases + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.DocumentDB/databaseAccounts + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Sql/servers/failoverGroups + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.ContainerService/managedClusters + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.App/containerApps + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Cache/redis + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.ServiceBus/namespaces + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Web/sites + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Compute/virtualMachines + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Compute/virtualMachineScaleSets + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Network/loadBalancers + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Network/applicationGateways + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Network/frontDoors + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.Network/trafficManagerProfiles + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency + - services: + - Microsoft.DBforPostgreSQL/flexibleServers + terraform_pattern: | + # === SQL Database Auto-Failover Group === + resource "azapi_resource" "sql_failover_group" { + type = "Microsoft.Sql/servers/failoverGroups@2023-08-01-preview" + name = var.failover_group_name + parent_id = azapi_resource.sql_server_primary.id + + body = { + properties = { + partnerServers = [ + { + id = azapi_resource.sql_server_secondary.id + } + ] + readWriteEndpoint = { + failoverPolicy = "Automatic" + failoverWithDataLossGracePeriodMinutes = 60 + } + readOnlyEndpoint = { + failoverPolicy = "Enabled" # Read-only endpoint fails over too + } + databases = [ + azapi_resource.sql_database.id + ] + } + } + } + + # === Cosmos DB Multi-Region Writes === + resource "azapi_resource" "cosmos_multi_region" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + parent_id = azapi_resource.resource_group.id + location = var.primary_location + + body = { + properties = { + databaseAccountOfferType = "Standard" + enableMultipleWriteLocations = true # Multi-region writes + enableAutomaticFailover = true # Automatic failover on region outage + locations = [ + { + locationName = var.primary_location + failoverPriority = 0 + isZoneRedundant = true + }, + { + locationName = var.secondary_location + failoverPriority = 1 + isZoneRedundant = true + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + maxIntervalInSeconds = 5 + maxStalenessPrefix = 100 + } + } + } + } + + # === PostgreSQL Flexible Read Replica === + resource "azapi_resource" "postgresql_replica" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01" + name = var.postgresql_replica_name + parent_id = azapi_resource.resource_group_secondary.id + location = var.secondary_location + + body = { + properties = { + createMode = "Replica" + sourceServerResourceId = azapi_resource.postgresql_primary.id + availabilityZone = "1" + } + } + } + bicep_pattern: | + // === SQL Database Auto-Failover Group === + resource sqlFailoverGroup 'Microsoft.Sql/servers/failoverGroups@2023-08-01-preview' = { + parent: sqlServerPrimary + name: failoverGroupName + properties: { + partnerServers: [ + { + id: sqlServerSecondary.id + } + ] + readWriteEndpoint: { + failoverPolicy: 'Automatic' + failoverWithDataLossGracePeriodMinutes: 60 + } + readOnlyEndpoint: { + failoverPolicy: 'Enabled' + } + databases: [ + sqlDatabase.id + ] + } + } + + // === Cosmos DB Multi-Region Writes === + resource cosmosMultiRegion 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: primaryLocation + properties: { + databaseAccountOfferType: 'Standard' + enableMultipleWriteLocations: true + enableAutomaticFailover: true + locations: [ + { + locationName: primaryLocation + failoverPriority: 0 + isZoneRedundant: true + } + { + locationName: secondaryLocation + failoverPriority: 1 + isZoneRedundant: true + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + maxIntervalInSeconds: 5 + maxStalenessPrefix: 100 + } + } + } + + // === PostgreSQL Flexible Read Replica === + resource postgresqlReplica 'Microsoft.DBforPostgreSQL/flexibleServers@2024-08-01' = { + name: postgresqlReplicaName + location: secondaryLocation + properties: { + createMode: 'Replica' + sourceServerResourceId: postgresqlPrimary.id + availabilityZone: '1' + } + } + prohibitions: + - NEVER deploy production SQL databases without failover groups or active geo-replication — RPO is limited to last backup + (hours) + - NEVER set failoverWithDataLossGracePeriodMinutes below 30 — too aggressive causes unnecessary failovers + - NEVER disable automatic failover on Cosmos DB with multiple regions — manual failover requires human intervention during + outages + - NEVER use Strong consistency for multi-region Cosmos DB writes — it requires synchronous cross-region replication and + dramatically increases latency +patterns: +- name: Health endpoint pattern + description: Implement a /healthz endpoint in every service that checks all downstream dependencies (database connectivity, + cache availability, external API reachability) and returns structured health status. + example: | + // ASP.NET Core health check pattern + builder.Services.AddHealthChecks() + .AddSqlServer(connectionString, name: "sql", tags: new[] { "ready" }) + .AddRedis(redisConnectionString, name: "redis", tags: new[] { "ready" }) + .AddUrlGroup(new Uri(externalApiUrl), name: "external-api", tags: new[] { "ready" }); + + app.MapHealthChecks("/healthz", new HealthCheckOptions { + Predicate = _ => true, + ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse + }); + + app.MapHealthChecks("/healthz/live", new HealthCheckOptions { + Predicate = _ => false // Liveness: just check process is running + }); + + app.MapHealthChecks("/healthz/ready", new HealthCheckOptions { + Predicate = check => check.Tags.Contains("ready") + }); +anti_patterns: +- description: Deploying all resources in a single availability zone without zone redundancy + instead: Spread resources across availability zones 1, 2, and 3 for datacenter-level fault tolerance +- description: Using TCP health probes that only check port availability + instead: Use HTTP/HTTPS health probes with /healthz endpoint that validates application and dependency health +- description: Relying on single-region deployment for production workloads + instead: Deploy to at least two regions with Front Door or Traffic Manager for automatic failover +- description: Using Standard_LRS storage for production data + instead: Use Standard_ZRS (zone-redundant) or Standard_GZRS (geo-zone-redundant) for production storage +- description: Deploying databases without geo-replication + instead: Configure SQL failover groups, Cosmos DB multi-region, or PostgreSQL read replicas for DR +references: +- title: Azure Well-Architected Framework — Reliability pillar + url: https://learn.microsoft.com/azure/well-architected/reliability/ +- title: Availability zones and regions + url: https://learn.microsoft.com/azure/reliability/availability-zones-overview +- title: Azure Front Door — origins and origin groups + url: https://learn.microsoft.com/azure/frontdoor/origin +- title: SQL Database auto-failover groups + url: https://learn.microsoft.com/azure/azure-sql/database/auto-failover-group-overview +- title: Health endpoint monitoring pattern + url: https://learn.microsoft.com/azure/architecture/patterns/health-endpoint-monitoring diff --git a/azext_prototype/governance/policies/security/authentication.policy.yaml b/azext_prototype/governance/policies/security/authentication.policy.yaml index 4d64bd7..72459d2 100644 --- a/azext_prototype/governance/policies/security/authentication.policy.yaml +++ b/azext_prototype/governance/policies/security/authentication.policy.yaml @@ -1,54 +1,115 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: authentication - category: security - services: [container-apps, app-service, functions, api-management, sql-database, cosmos-db] - last_reviewed: "2026-02-01" - -rules: - - id: AUTH-001 - severity: required - description: "Never hardcode credentials, API keys, or secrets in source code, config files, or environment variables" - rationale: "Hardcoded secrets leak through source control, logs, and error messages" - applies_to: [cloud-architect, app-developer, terraform-agent, bicep-agent, biz-analyst] - - - id: AUTH-002 - severity: recommended - description: "Assign least-privilege RBAC roles for all service principals and user accounts" - rationale: "Principle of least privilege limits blast radius of compromised credentials" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - - - id: AUTH-003 - severity: recommended - description: "Prefer app registrations with scoped permissions over shared API keys for client authentication" - rationale: "App registrations support scoped permissions, token expiry, and audit logging" - applies_to: [cloud-architect, app-developer, biz-analyst] - -patterns: - - name: "Managed identity for service-to-service" - description: "Use managed identity to avoid storing credentials" - example: | - from azure.identity import DefaultAzureCredential - credential = DefaultAzureCredential() - # Works with managed identity in Azure, developer credentials locally - - - name: "Key Vault for external secrets" - description: "Store third-party API keys or connection strings in Key Vault" - example: | - from azure.keyvault.secrets import SecretClient - client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential) - secret = client.get_secret("external-api-key") - -anti_patterns: - - description: "Do not embed API keys or passwords in application source code" - instead: "Use managed identity for Azure services or Key Vault for external secrets" - - description: "Do not assign Owner or Contributor roles at subscription or resource group scope" - instead: "Use the most specific built-in role at the narrowest scope possible" - -references: - - title: "Azure RBAC best practices" - url: "https://learn.microsoft.com/azure/role-based-access-control/best-practices" - - title: "DefaultAzureCredential overview" - url: "https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential" +kind: policy +domain: security +description: Governance policies for Authentication +last_updated: '2026-02-01' +rules: +- id: WAF-SEC-AUTH-001 + severity: required + description: Never hardcode credentials, API keys, or secrets in source code, config files, or environment variables + rationale: Hardcoded secrets leak through source control, logs, and error messages + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - terraform-agent + - bicep-agent + - biz-analyst + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.ContainerRegistry/registries + - Microsoft.ContainerService/managedClusters +- id: WAF-SEC-AUTH-002 + severity: recommended + description: Assign least-privilege RBAC roles for all service principals and user accounts + rationale: Principle of least privilege limits blast radius of compromised credentials + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.ContainerRegistry/registries + - Microsoft.ContainerService/managedClusters +- id: WAF-SEC-AUTH-003 + severity: recommended + description: Prefer app registrations with scoped permissions over shared API keys for client authentication + rationale: App registrations support scoped permissions, token expiry, and audit logging + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - biz-analyst + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.ApiManagement/service + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.Cache/redis + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices +patterns: +- name: Managed identity for service-to-service + description: Use managed identity to avoid storing credentials + example: 'from azure.identity import DefaultAzureCredential + + credential = DefaultAzureCredential() + + # Works with managed identity in Azure, developer credentials locally + + ' +- name: Key Vault for external secrets + description: Store third-party API keys or connection strings in Key Vault + example: 'from azure.keyvault.secrets import SecretClient + + client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential) + + secret = client.get_secret("external-api-key") + + ' +anti_patterns: +- description: Do not embed API keys or passwords in application source code + instead: Use managed identity for Azure services or Key Vault for external secrets +- description: Do not assign Owner or Contributor roles at subscription or resource group scope + instead: Use the most specific built-in role at the narrowest scope possible +references: +- title: Azure RBAC best practices + url: https://learn.microsoft.com/azure/role-based-access-control/best-practices +- title: DefaultAzureCredential overview + url: https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential diff --git a/azext_prototype/governance/policies/security/data-protection.policy.yaml b/azext_prototype/governance/policies/security/data-protection.policy.yaml index f18226f..da9feda 100644 --- a/azext_prototype/governance/policies/security/data-protection.policy.yaml +++ b/azext_prototype/governance/policies/security/data-protection.policy.yaml @@ -1,65 +1,138 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: data-protection - category: security - services: [sql-database, cosmos-db, storage, key-vault] - last_reviewed: "2026-02-01" - -rules: - - id: DP-001 - severity: required - description: "Enable encryption at rest for all data services (TDE, SSE, or service-managed keys)" - rationale: "Encryption at rest is enabled by default on most Azure services; ensure it is not disabled" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - - - id: DP-002 - severity: required - description: "Enforce TLS 1.2+ for all data-in-transit connections" - rationale: "Older TLS versions have known vulnerabilities" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: DP-003 - severity: recommended - description: "Store application secrets and connection configuration in Azure Key Vault, not in code or environment variables" - rationale: "Key Vault provides auditing, rotation support, and access control for secrets" - applies_to: [cloud-architect, app-developer, biz-analyst] - - - id: DP-004 - severity: recommended - description: "Use Azure Key Vault references in App Service and Container Apps configuration instead of plaintext secrets" - rationale: "Key Vault references are resolved at runtime, avoiding secret sprawl" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer] - -patterns: - - name: "Key Vault reference in Container Apps" - description: "Reference a Key Vault secret from Container App environment variable" - example: | - resource "azurerm_container_app" "api" { - template { - container { - env { - name = "DB_CONNECTION" - secret_name = "db-conn" - } - } - } - secret { - name = "db-conn" - key_vault_secret_id = azurerm_key_vault_secret.db_conn.versionless_id - identity = "System" - } - } - -anti_patterns: - - description: "Do not hardcode secrets, API keys, or connection strings in application code or config files" - instead: "Use Key Vault references or managed identity for credential-free access" - - description: "Do not disable TDE or encryption at rest on any data service" - instead: "Leave default encryption settings enabled; use customer-managed keys only if required" - -references: - - title: "Azure encryption at rest overview" - url: "https://learn.microsoft.com/azure/security/fundamentals/encryption-atrest" - - title: "Key Vault references for App Service" - url: "https://learn.microsoft.com/azure/app-service/app-service-key-vault-references" +kind: policy +domain: security +description: Governance policies for Data Protection +last_updated: '2026-02-01' +rules: +- id: WAF-SEC-DP-001 + severity: required + description: Enable encryption at rest for all data services (TDE, SSE, or service-managed keys) + rationale: Encryption at rest is enabled by default on most Azure services; ensure it is not disabled + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Search/searchServices + - Microsoft.CognitiveServices/accounts +- id: WAF-SEC-DP-002 + severity: required + description: Enforce TLS 1.2+ for all data-in-transit connections + rationale: Older TLS versions have known vulnerabilities + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Search/searchServices + - Microsoft.CognitiveServices/accounts + - Microsoft.ContainerRegistry/registries +- id: WAF-SEC-DP-003 + severity: recommended + description: Store application secrets and connection configuration in Azure Key Vault, not in code or environment variables + rationale: Key Vault provides auditing, rotation support, and access control for secrets + applies_to: + - cloud-architect + - app-developer + - csharp-developer + - python-developer + - biz-analyst + targets: + - services: + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.KeyVault/vaults + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts +- id: WAF-SEC-DP-004 + severity: recommended + description: Use Azure Key Vault references in App Service and Container Apps configuration instead of plaintext secrets + rationale: Key Vault references are resolved at runtime, avoiding secret sprawl + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.CognitiveServices/accounts +patterns: +- name: Key Vault reference in Container Apps + description: Reference a Key Vault secret from Container App environment variable + example: | + resource "azapi_resource" "container_app_api" { + type = "Microsoft.App/containerApps@2024-03-01" + parent_id = azapi_resource.resource_group.id + name = "api" + body = { + properties = { + configuration = { + secrets = [{ + name = "db-conn" + keyVaultUrl = azapi_resource.key_vault_secret_db_conn.output.properties.secretUriWithVersion + identity = "System" + }] + } + template = { + containers = [{ + name = "api" + image = "app:latest" + env = [{ + name = "DB_CONNECTION" + secretRef = "db-conn" + }] + }] + } + } + } + } +anti_patterns: +- description: Do not hardcode secrets, API keys, or connection strings in application code or config files + instead: Use Key Vault references or managed identity for credential-free access +- description: Do not disable TDE or encryption at rest on any data service + instead: Leave default encryption settings enabled; use customer-managed keys only if required +references: +- title: Azure encryption at rest overview + url: https://learn.microsoft.com/azure/security/fundamentals/encryption-atrest +- title: Key Vault references for App Service + url: https://learn.microsoft.com/azure/app-service/app-service-key-vault-references diff --git a/azext_prototype/governance/policies/security/managed-identity.policy.yaml b/azext_prototype/governance/policies/security/managed-identity.policy.yaml index 37b96e4..14b213f 100644 --- a/azext_prototype/governance/policies/security/managed-identity.policy.yaml +++ b/azext_prototype/governance/policies/security/managed-identity.policy.yaml @@ -1,60 +1,154 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: managed-identity - category: security - services: [container-apps, app-service, functions, key-vault, sql-database, cosmos-db, storage] - last_reviewed: "2025-12-01" - -rules: - - id: MI-001 - severity: required - description: "Use system-assigned managed identity for single-service resources" - rationale: "Lifecycle tied to the resource, no orphaned identities" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - scope: [container-apps, functions, app-service, api-management, container-registry] - require_config: [identity] - error_message: "Service '{service_name}' ({service_type}) does not configure managed identity" - - - id: MI-002 - severity: required - description: "Use user-assigned managed identity when identity is shared across resources" - rationale: "Avoids role assignment duplication and simplifies rotation" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: MI-003 - severity: required - description: "Never use service principal client secrets for service-to-service auth" - rationale: "Secrets expire, rotate, and leak; managed identity eliminates this" - applies_to: [cloud-architect, terraform-agent, bicep-agent, app-developer, biz-analyst] - - - id: MI-004 - severity: recommended - description: "Assign least-privilege RBAC roles, never Owner or Contributor at resource group scope" - rationale: "Principle of least privilege reduces blast radius" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - -patterns: - - name: "System-assigned identity with role" - description: "Enable system identity and assign a specific role" - example: | - resource "azurerm_container_app" "app" { - identity { - type = "SystemAssigned" - } - } - resource "azurerm_role_assignment" "kv_reader" { - principal_id = azurerm_container_app.app.identity[0].principal_id - role_definition_name = "Key Vault Secrets User" - scope = azurerm_key_vault.main.id - } - -anti_patterns: - - description: "Do not store client secrets or certificates in application config" - instead: "Use managed identity; the Azure SDK handles token acquisition automatically" - -references: - - title: "Managed identities overview" - url: "https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview" +kind: policy +domain: security +description: Governance policies for Managed Identity +last_updated: '2025-12-01' +rules: +- id: WAF-SEC-MI-001 + severity: required + description: Use system-assigned managed identity for single-service resources + rationale: Lifecycle tied to the resource, no orphaned identities + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + template_check: + scope: + - container-apps + - functions + - app-service + - api-management + - container-registry + require_config: + - identity + error_message: Service '{service_name}' ({service_type}) does not configure managed identity + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers +- id: WAF-SEC-MI-002 + severity: required + description: Use user-assigned managed identity when identity is shared across resources + rationale: Avoids role assignment duplication and simplifies rotation + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers +- id: WAF-SEC-MI-003 + severity: required + description: Never use service principal client secrets for service-to-service auth + rationale: Secrets expire, rotate, and leak; managed identity eliminates this + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - biz-analyst + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers +- id: WAF-SEC-MI-004 + severity: recommended + description: Assign least-privilege RBAC roles, never Owner or Contributor at resource group scope + rationale: Principle of least privilege reduces blast radius + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.Cache/redis + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers +patterns: +- name: System-assigned identity with role + description: Enable system identity and assign a specific role + example: | + resource "azapi_resource" "container_app" { + type = "Microsoft.App/containerApps@2024-03-01" + parent_id = azapi_resource.resource_group.id + name = "app" + body = { + properties = { ... } + identity = { + type = "SystemAssigned" + } + } + } + resource "azapi_resource" "kv_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + parent_id = azapi_resource.key_vault.id + name = uuidv5("oid", "${azapi_resource.container_app.output.identity.principalId}-Key Vault Secrets User") + body = { + properties = { + principalId = azapi_resource.container_app.output.identity.principalId + roleDefinitionId = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" + principalType = "ServicePrincipal" + } + } + } +anti_patterns: +- description: Do not store client secrets or certificates in application config + instead: Use managed identity; the Azure SDK handles token acquisition automatically +references: +- title: Managed identities overview + url: https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview diff --git a/azext_prototype/governance/policies/security/network-isolation.policy.yaml b/azext_prototype/governance/policies/security/network-isolation.policy.yaml index 028fa60..9a42ee5 100644 --- a/azext_prototype/governance/policies/security/network-isolation.policy.yaml +++ b/azext_prototype/governance/policies/security/network-isolation.policy.yaml @@ -1,65 +1,179 @@ -# yaml-language-server: $schema=../policy.schema.json -apiVersion: v1 -kind: policy -metadata: - name: network-isolation - category: security - services: [container-apps, app-service, key-vault, sql-database, cosmos-db, storage] - last_reviewed: "2025-12-01" - -rules: - - id: NET-001 - severity: required - description: "Use private endpoints for all PaaS data services in production" - rationale: "Eliminates public internet exposure for data plane" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - scope: [key-vault, sql-database, cosmos-db, storage] - require_config: [private_endpoint] - error_message: "Service '{service_name}' ({service_type}) missing private_endpoint: true" - - - id: NET-002 - severity: required - description: "Deploy workloads in a dedicated subnet within the landing zone VNET" - rationale: "Network segmentation enables NSG and route table controls" - applies_to: [cloud-architect, terraform-agent, bicep-agent, biz-analyst] - template_check: - require_service: [virtual-network] - error_message: "Template missing a virtual-network service for network isolation" - - - id: NET-003 - severity: recommended - description: "Use NSGs to restrict traffic between subnets to only required ports" - rationale: "Defence in depth beyond private endpoints" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - - - id: NET-004 - severity: recommended - description: "Enable diagnostic logging on NSGs for traffic auditing" - rationale: "Required for incident investigation and compliance" - applies_to: [cloud-architect, terraform-agent, bicep-agent] - -patterns: - - name: "Private endpoint for Key Vault" - description: "Create private endpoint and disable public access" - example: | - resource "azurerm_private_endpoint" "kv" { - name = "pe-kv-${var.project}" - subnet_id = azurerm_subnet.private.id - private_service_connection { - name = "kv-connection" - private_connection_resource_id = azurerm_key_vault.main.id - subresource_names = ["vault"] - is_manual_connection = false - } - } - -anti_patterns: - - description: "Do not allow 0.0.0.0/0 in any NSG or firewall rule" - instead: "Use specific IP ranges or service tags" - - description: "Do not rely solely on service firewalls without VNET integration" - instead: "Use private endpoints + VNET integration for defense in depth" - -references: - - title: "Private Link overview" - url: "https://learn.microsoft.com/azure/private-link/private-link-overview" +kind: policy +domain: security +description: Governance policies for Network Isolation +last_updated: '2025-12-01' +rules: +- id: WAF-SEC-NET-001 + severity: required + description: Disable public network access AND use private endpoints for all PaaS data services. Set publicNetworkAccess + to Disabled (or public_network_access_enabled to false) on every PaaS resource. NEVER generate public_network_access_enabled + = true or publicNetworkAccess = Enabled. + rationale: Eliminates public internet exposure for data plane. Both disabling public access AND adding private endpoints + are required — private endpoints alone do not block public access. + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + template_check: + scope: + - key-vault + - sql-database + - cosmos-db + - storage + require_config: + - private_endpoint + error_message: 'Service ''{service_name}'' ({service_type}) missing private_endpoint: true' + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.ContainerRegistry/registries + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.OperationalInsights/workspaces +- id: WAF-SEC-NET-002 + severity: required + description: Deploy workloads in a dedicated subnet within the landing zone VNET + rationale: Network segmentation enables NSG and route table controls + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + - biz-analyst + template_check: + require_service: + - virtual-network + error_message: Template missing a virtual-network service for network isolation + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.ContainerRegistry/registries + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.ContainerService/managedClusters +- id: WAF-SEC-NET-005 + severity: required + description: Every Azure PaaS resource that supports publicNetworkAccess MUST explicitly set it to Disabled — including + publicNetworkAccessForIngestion and publicNetworkAccessForQuery on Log Analytics and Application Insights. This applies + to ALL environments including POC and development. There are NO exceptions — POC environments MUST be secure. In Terraform + azapi_resource body blocks, set publicNetworkAccess = "Disabled". In Bicep, set properties.publicNetworkAccess = 'Disabled'. + rationale: Azure PaaS services default to public access enabled. Omitting the property results in a public endpoint. This + rule applies to POC, development, AND production — there are no security exemptions for non-production environments. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ServiceBus/namespaces + - Microsoft.EventHub/namespaces + - Microsoft.ContainerRegistry/registries + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices + - Microsoft.OperationalInsights/workspaces +- id: WAF-SEC-NET-003 + severity: recommended + description: Use NSGs to restrict traffic between subnets to only required ports + rationale: Defence in depth beyond private endpoints + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices +- id: WAF-SEC-NET-004 + severity: recommended + description: Enable diagnostic logging on NSGs for traffic auditing + rationale: Required for incident investigation and compliance + applies_to: + - cloud-architect + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.App/containerApps + - Microsoft.Web/sites + - Microsoft.KeyVault/vaults + - Microsoft.Sql/servers/databases + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.Storage/storageAccounts + - Microsoft.Cache/redis + - Microsoft.DBforPostgreSQL/flexibleServers + - Microsoft.DBforMySQL/flexibleServers + - Microsoft.ContainerService/managedClusters + - Microsoft.ContainerRegistry/registries + - Microsoft.CognitiveServices/accounts + - Microsoft.Search/searchServices +patterns: +- name: Private endpoint for Key Vault + description: Create private endpoint and disable public access + example: | + resource "azapi_resource" "private_endpoint_kv" { + type = "Microsoft.Network/privateEndpoints@2023-11-01" + parent_id = azapi_resource.resource_group.id + name = "pe-kv-${var.project}" + location = var.location + body = { + properties = { + subnet = { + id = azapi_resource.subnet_private.output.id + } + privateLinkServiceConnections = [{ + name = "kv-connection" + properties = { + privateLinkServiceId = azapi_resource.key_vault.id + groupIds = ["vault"] + } + }] + } + } + } +anti_patterns: +- description: Do not allow 0.0.0.0/0 in any NSG or firewall rule + instead: Use specific IP ranges or service tags +- description: Do not rely solely on service firewalls without VNET integration + instead: Use private endpoints + VNET integration for defense in depth +references: +- title: Private Link overview + url: https://learn.microsoft.com/azure/private-link/private-link-overview diff --git a/azext_prototype/governance/policies/validate.py b/azext_prototype/governance/policies/validate.py index 1ab7e14..62fbc1b 100644 --- a/azext_prototype/governance/policies/validate.py +++ b/azext_prototype/governance/policies/validate.py @@ -1,140 +1,144 @@ -#!/usr/bin/env python -"""Validate .policy.yaml files against the governance schema. - -Usage: - # Validate all built-in policies - python -m azext_prototype.governance.policies.validate - - # Validate specific files - python -m azext_prototype.governance.policies.validate path/to/policy.yaml ... - - # Validate a directory recursively - python -m azext_prototype.governance.policies.validate --dir azext_prototype/policies/ - - # Strict mode — warnings are treated as errors - python -m azext_prototype.governance.policies.validate --strict - - # As a pre-commit hook (validates staged .policy.yaml files) - python -m azext_prototype.governance.policies.validate --hook - -Exit codes: - 0 — all files valid - 1 — validation errors found -""" - -from __future__ import annotations - -import argparse -import subprocess -import sys -from pathlib import Path - -from azext_prototype.governance.policies import ( - validate_policy_directory, - validate_policy_file, -) - - -def _get_staged_policy_files() -> list[Path]: - """Return staged .policy.yaml files from the git index.""" - try: - result = subprocess.run( - ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"], - capture_output=True, - text=True, - check=True, - ) - except (subprocess.CalledProcessError, FileNotFoundError): - return [] - - return [Path(f) for f in result.stdout.strip().splitlines() if f.endswith(".policy.yaml")] - - -def main(argv: list[str] | None = None) -> int: - """Entry point for the policy validator.""" - parser = argparse.ArgumentParser(description="Validate .policy.yaml files against the governance schema.") - parser.add_argument( - "files", - nargs="*", - help="Specific .policy.yaml files to validate.", - ) - parser.add_argument( - "--dir", - type=str, - default=None, - help="Validate all .policy.yaml files under this directory recursively.", - ) - parser.add_argument( - "--strict", - action="store_true", - help="Treat warnings as errors.", - ) - parser.add_argument( - "--hook", - action="store_true", - help="Pre-commit hook mode: validate staged .policy.yaml files.", - ) - - args = parser.parse_args(argv) - - errors = [] - - if args.hook: - # Pre-commit mode — only check staged files - staged = _get_staged_policy_files() - if not staged: - return 0 - sys.stdout.write(f"Validating {len(staged)} staged policy file(s)...\n") - for path in staged: - errors.extend(validate_policy_file(path)) - - elif args.dir: - # Directory mode - directory = Path(args.dir) - if not directory.is_dir(): - sys.stderr.write(f"Error: '{args.dir}' is not a directory\n") - return 1 - policy_files = sorted(directory.rglob("*.policy.yaml")) - sys.stdout.write(f"Validating {len(policy_files)} policy file(s) in {args.dir}...\n") - errors.extend(validate_policy_directory(directory)) - - elif args.files: - # Explicit file list - sys.stdout.write(f"Validating {len(args.files)} policy file(s)...\n") - for filepath in args.files: - path = Path(filepath) - if not path.exists(): - sys.stderr.write(f"Error: '{filepath}' does not exist\n") - return 1 - errors.extend(validate_policy_file(path)) - - else: - # Default: validate built-in policies - builtin_dir = Path(__file__).parent - policy_files = sorted(builtin_dir.rglob("*.policy.yaml")) - sys.stdout.write(f"Validating {len(policy_files)} built-in policy file(s)...\n") - errors.extend(validate_policy_directory(builtin_dir)) - - # Report results - if not errors: - sys.stdout.write("All policy files are valid.\n") - return 0 - - actual_errors = [e for e in errors if e.severity == "error"] - warnings = [e for e in errors if e.severity == "warning"] - - for err in errors: - sys.stdout.write(f"{err}\n") - - sys.stdout.write(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)\n") - - if actual_errors: - return 1 - if args.strict and warnings: - return 1 - - return 0 - - -if __name__ == "__main__": - sys.exit(main()) +#!/usr/bin/env python +"""Validate .policy.yaml files against the governance schema. + +This is the original policy-only validator. For unified governance +validation (policies + anti-patterns + standards), use: + python -m azext_prototype.governance.validate --all --strict + +Usage: + # Validate all built-in policies + python -m azext_prototype.governance.policies.validate + + # Validate specific files + python -m azext_prototype.governance.policies.validate path/to/policy.yaml ... + + # Validate a directory recursively + python -m azext_prototype.governance.policies.validate --dir azext_prototype/policies/ + + # Strict mode — warnings are treated as errors + python -m azext_prototype.governance.policies.validate --strict + + # As a pre-commit hook (validates staged .policy.yaml files) + python -m azext_prototype.governance.policies.validate --hook + +Exit codes: + 0 — all files valid + 1 — validation errors found +""" + +from __future__ import annotations + +import argparse +import subprocess +import sys +from pathlib import Path + +from azext_prototype.governance.policies import ( + validate_policy_directory, + validate_policy_file, +) + + +def _get_staged_policy_files() -> list[Path]: + """Return staged .policy.yaml files from the git index.""" + try: + result = subprocess.run( + ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"], + capture_output=True, + text=True, + check=True, + ) + except (subprocess.CalledProcessError, FileNotFoundError): + return [] + + return [Path(f) for f in result.stdout.strip().splitlines() if f.endswith(".policy.yaml")] + + +def main(argv: list[str] | None = None) -> int: + """Entry point for the policy validator.""" + parser = argparse.ArgumentParser(description="Validate .policy.yaml files against the governance schema.") + parser.add_argument( + "files", + nargs="*", + help="Specific .policy.yaml files to validate.", + ) + parser.add_argument( + "--dir", + type=str, + default=None, + help="Validate all .policy.yaml files under this directory recursively.", + ) + parser.add_argument( + "--strict", + action="store_true", + help="Treat warnings as errors.", + ) + parser.add_argument( + "--hook", + action="store_true", + help="Pre-commit hook mode: validate staged .policy.yaml files.", + ) + + args = parser.parse_args(argv) + + errors = [] + + if args.hook: + # Pre-commit mode — only check staged files + staged = _get_staged_policy_files() + if not staged: + return 0 + sys.stdout.write(f"Validating {len(staged)} staged policy file(s)...\n") + for path in staged: + errors.extend(validate_policy_file(path)) + + elif args.dir: + # Directory mode + directory = Path(args.dir) + if not directory.is_dir(): + sys.stderr.write(f"Error: '{args.dir}' is not a directory\n") + return 1 + policy_files = sorted(directory.rglob("*.policy.yaml")) + sys.stdout.write(f"Validating {len(policy_files)} policy file(s) in {args.dir}...\n") + errors.extend(validate_policy_directory(directory)) + + elif args.files: + # Explicit file list + sys.stdout.write(f"Validating {len(args.files)} policy file(s)...\n") + for filepath in args.files: + path = Path(filepath) + if not path.exists(): + sys.stderr.write(f"Error: '{filepath}' does not exist\n") + return 1 + errors.extend(validate_policy_file(path)) + + else: + # Default: validate built-in policies + builtin_dir = Path(__file__).parent + policy_files = sorted(builtin_dir.rglob("*.policy.yaml")) + sys.stdout.write(f"Validating {len(policy_files)} built-in policy file(s)...\n") + errors.extend(validate_policy_directory(builtin_dir)) + + # Report results + if not errors: + sys.stdout.write("All policy files are valid.\n") + return 0 + + actual_errors = [e for e in errors if e.severity == "error"] + warnings = [e for e in errors if e.severity == "warning"] + + for err in errors: + sys.stdout.write(f"{err}\n") + + sys.stdout.write(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)\n") + + if actual_errors: + return 1 + if args.strict and warnings: + return 1 + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/azext_prototype/governance/schemas/__init__.py b/azext_prototype/governance/schemas/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/schemas/anti-pattern.schema.json b/azext_prototype/governance/schemas/anti-pattern.schema.json new file mode 100644 index 0000000..53886d3 --- /dev/null +++ b/azext_prototype/governance/schemas/anti-pattern.schema.json @@ -0,0 +1,93 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Governance Anti-Pattern", + "description": "Schema for anti-pattern YAML governance files. All anti-patterns share the unified top-level metadata (kind, domain, description, last_updated) and contain a patterns array.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["anti-pattern"], + "description": "Governance kind. Must be 'anti-pattern'." + }, + "domain": { + "type": "string", + "description": "Anti-pattern domain (e.g. 'security', 'networking', 'encryption')." + }, + "description": { + "type": "string", + "description": "Human-readable description of this anti-pattern domain." + }, + "last_updated": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "Date the anti-pattern was last updated (YYYY-MM-DD)." + }, + "patterns": { + "type": "array", + "description": "Anti-patterns to detect in generated output.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique anti-pattern identifier (e.g. 'ANTI-SEC-001')." + }, + "description": { + "type": "string", + "description": "What this anti-pattern detects." + }, + "rationale": { + "type": "string", + "description": "Why this is an anti-pattern." + }, + "warning_message": { + "type": "string", + "description": "Human-readable warning shown when pattern is detected." + }, + "applies_to": { + "type": "array", + "items": { "type": "string" }, + "description": "Agent names this pattern applies to (e.g. ['terraform-agent', 'bicep-agent'])." + }, + "targets": { + "type": "array", + "description": "Detection targets — each entry specifies services and search/safe/correct patterns.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "services": { + "type": "array", + "items": { "type": "string" }, + "description": "ARM resource type namespaces. Empty or absent means all services." + }, + "search_patterns": { + "type": "array", + "items": { "type": "string" }, + "minItems": 1, + "description": "Substrings to search for (case-insensitive)." + }, + "safe_patterns": { + "type": "array", + "items": { "type": "string" }, + "description": "Substrings that exempt a match (case-insensitive)." + }, + "correct_patterns": { + "type": "array", + "items": { "type": "string" }, + "description": "Examples of correct code to show when pattern is detected." + } + }, + "required": ["search_patterns"], + "additionalProperties": false + } + } + }, + "required": ["id", "description", "warning_message", "targets"] + } + } + }, + "required": ["kind", "domain", "description", "last_updated", "patterns"], + "additionalProperties": false +} diff --git a/azext_prototype/governance/schemas/policy.schema.json b/azext_prototype/governance/schemas/policy.schema.json new file mode 100644 index 0000000..36e660f --- /dev/null +++ b/azext_prototype/governance/schemas/policy.schema.json @@ -0,0 +1,202 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Governance Policy", + "description": "Schema for .policy.yaml governance files. All policies share the unified top-level metadata (kind, domain, description, last_updated) and contain a rules array.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["policy"], + "description": "Governance kind. Must be 'policy'." + }, + "domain": { + "type": "string", + "description": "Policy domain (e.g. 'azure-data', 'security', 'cost')." + }, + "description": { + "type": "string", + "description": "Human-readable description of this policy file." + }, + "last_updated": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "Date the policy was last updated (YYYY-MM-DD)." + }, + "rules": { + "type": "array", + "description": "Governance rules agents must follow.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique rule identifier (e.g. 'AZ-SQL-001')." + }, + "severity": { + "type": "string", + "enum": ["required", "recommended", "optional"], + "description": "Rule severity level." + }, + "description": { + "type": "string", + "description": "What the rule requires." + }, + "rationale": { + "type": "string", + "description": "Why this rule exists." + }, + "warning_message": { + "type": "string", + "description": "Human-readable warning shown when rule is violated." + }, + "applies_to": { + "type": "array", + "items": { "type": "string" }, + "description": "Agent names this rule applies to (e.g. ['terraform-agent', 'bicep-agent'])." + }, + "targets": { + "type": "array", + "description": "Service targets and implementation patterns. Each entry specifies services and patterns.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "services": { + "type": "array", + "items": { "type": "string" }, + "description": "ARM resource type namespaces (e.g. ['Microsoft.Sql/servers'])." + }, + "terraform_pattern": { + "type": "string", + "description": "Terraform code pattern (optional — only for infrastructure agents)." + }, + "bicep_pattern": { + "type": "string", + "description": "Bicep code pattern (optional — only for infrastructure agents)." + }, + "csharp_pattern": { + "type": "string", + "description": "C# code pattern (optional — only for csharp-developer)." + }, + "python_pattern": { + "type": "string", + "description": "Python code pattern (optional — only for python-developer)." + }, + "react_pattern": { + "type": "string", + "description": "React/TypeScript code pattern (optional — only for react-developer)." + }, + "prohibitions": { + "type": "array", + "items": { "type": "string" }, + "description": "Things the agent must NEVER generate for these services." + } + }, + "additionalProperties": false + } + }, + "companion_resources": { + "type": "array", + "description": "Resources that MUST be created alongside the primary resource.", + "items": { + "type": "object", + "properties": { + "type": { "type": "string" }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "terraform_pattern": { "type": "string" }, + "bicep_pattern": { "type": "string" } + }, + "required": ["type", "name", "description"], + "additionalProperties": false + } + }, + "prohibitions": { + "type": "array", + "description": "Explicit list of things the agent must NEVER generate.", + "items": { "type": "string" } + }, + "template_check": { + "type": "object", + "description": "Optional automated compliance check applied to workload templates.", + "properties": { + "scope": { + "oneOf": [ + { "type": "string" }, + { "type": "array", "items": { "type": "string" } } + ] + }, + "require_config": { + "oneOf": [ + { "type": "string" }, + { "type": "array", "items": { "type": "string" } } + ] + }, + "require_config_value": { "type": "object", "additionalProperties": true }, + "reject_config_value": { "type": "object", "additionalProperties": true }, + "require_service": { + "oneOf": [ + { "type": "string" }, + { "type": "array", "items": { "type": "string" } } + ] + }, + "when_services_present": { + "oneOf": [ + { "type": "string" }, + { "type": "array", "items": { "type": "string" } } + ] + }, + "severity": { "type": "string", "enum": ["error", "warning"] }, + "error_message": { "type": "string" } + }, + "additionalProperties": false + } + }, + "required": ["id", "severity", "description"] + } + }, + "patterns": { + "type": "array", + "description": "Implementation patterns agents should generate.", + "items": { + "type": "object", + "properties": { + "name": { "type": "string" }, + "description": { "type": "string" }, + "example": { "type": "string" } + }, + "required": ["name", "description"], + "additionalProperties": false + } + }, + "anti_patterns": { + "type": "array", + "description": "Inline anti-patterns agents must avoid (lightweight, policy-scoped).", + "items": { + "type": "object", + "properties": { + "description": { "type": "string" }, + "instead": { "type": "string" } + }, + "required": ["description"], + "additionalProperties": false + } + }, + "references": { + "type": "array", + "description": "Documentation references.", + "items": { + "type": "object", + "properties": { + "title": { "type": "string" }, + "url": { "type": "string", "format": "uri" } + }, + "required": ["title", "url"], + "additionalProperties": false + } + } + }, + "required": ["kind", "domain", "description", "last_updated", "rules"], + "additionalProperties": false +} diff --git a/azext_prototype/governance/schemas/standard.schema.json b/azext_prototype/governance/schemas/standard.schema.json new file mode 100644 index 0000000..f677861 --- /dev/null +++ b/azext_prototype/governance/schemas/standard.schema.json @@ -0,0 +1,61 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Governance Standard", + "description": "Schema for standards YAML governance files. All standards share the unified top-level metadata (kind, domain, description, last_updated) and contain a principles array.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["standard"], + "description": "Governance kind. Must be 'standard'." + }, + "domain": { + "type": "string", + "description": "Standard domain (e.g. 'terraform', 'python', 'coding', 'design')." + }, + "description": { + "type": "string", + "description": "Human-readable description of this standards domain." + }, + "last_updated": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "Date the standard was last updated (YYYY-MM-DD)." + }, + "principles": { + "type": "array", + "description": "Design principles and standards.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Unique principle identifier (e.g. 'STAN-TF-001')." + }, + "description": { + "type": "string", + "description": "What this principle requires." + }, + "rationale": { + "type": "string", + "description": "Why this principle exists." + }, + "applies_to": { + "type": "array", + "items": { "type": "string" }, + "description": "Agent names this principle applies to (e.g. ['terraform-agent', 'infrastructure-architect'])." + }, + "examples": { + "type": "array", + "items": { "type": "string" }, + "description": "Code or configuration examples." + } + }, + "required": ["id", "description"] + } + } + }, + "required": ["kind", "domain", "description", "last_updated", "principles"], + "additionalProperties": false +} diff --git a/azext_prototype/governance/schemas/transform.schema.json b/azext_prototype/governance/schemas/transform.schema.json new file mode 100644 index 0000000..f41eeba --- /dev/null +++ b/azext_prototype/governance/schemas/transform.schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Transform", + "description": "Post-generation transform rule for automatic fabrication fixes", + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "transform" + }, + "domain": { + "type": "string", + "description": "Governance domain (e.g., monitoring, data)" + }, + "description": { + "type": "string" + }, + "last_updated": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$" + }, + "transforms": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { "type": "string" }, + "description": { "type": "string" }, + "rationale": { "type": "string" }, + "applies_to": { + "type": "array", + "items": { "type": "string" } + }, + "targets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "services": { + "type": "array", + "items": { "type": "string" } + } + } + } + }, + "type": { + "type": "string", + "enum": ["regex", "structured"] + }, + "search": { "type": "string" }, + "replace": { "type": "string" } + }, + "required": ["id", "description", "search", "replace"], + "additionalProperties": false + } + } + }, + "required": ["kind", "domain", "description", "last_updated", "transforms"], + "additionalProperties": false +} diff --git a/azext_prototype/governance/standards/__init__.py b/azext_prototype/governance/standards/__init__.py index 50c39c5..020efd5 100644 --- a/azext_prototype/governance/standards/__init__.py +++ b/azext_prototype/governance/standards/__init__.py @@ -7,12 +7,15 @@ Directory layout:: standards/ - principles/ Design principles (DRY, SOLID, etc.) - design.yaml + application/ Application code patterns + dotnet.yaml + python.yaml + iac/ Infrastructure-as-Code patterns + bicep.yaml + terraform.yaml + principles/ Design principles coding.yaml - terraform/ Reference patterns per service type - bicep/ Reference patterns per service type - application/ Code patterns per language/framework + design.yaml """ from __future__ import annotations @@ -21,7 +24,7 @@ from dataclasses import dataclass, field from pathlib import Path -import yaml +from azext_prototype.governance import safe_load_yaml logger = logging.getLogger(__name__) @@ -34,8 +37,9 @@ class StandardPrinciple: """A single design principle or coding standard.""" id: str - name: str + name: str # kept for backward compat; new format merges into description description: str + rationale: str = "" applies_to: list[str] = field(default_factory=list) examples: list[str] = field(default_factory=list) @@ -45,8 +49,8 @@ class Standard: """A loaded standards document.""" domain: str - category: str description: str = "" + last_updated: str = "" principles: list[StandardPrinciple] = field(default_factory=list) @@ -65,12 +69,7 @@ def load(directory: Path | None = None) -> list[Standard]: return _cache for yaml_file in sorted(target.rglob("*.yaml")): - try: - data = yaml.safe_load(yaml_file.read_text(encoding="utf-8")) or {} - except (OSError, yaml.YAMLError) as exc: - logger.warning("Could not load standards file %s: %s", yaml_file.name, exc) - continue - + data = safe_load_yaml(yaml_file) if not isinstance(data, dict): continue @@ -83,6 +82,7 @@ def load(directory: Path | None = None) -> list[Standard]: id=entry.get("id", ""), name=entry.get("name", ""), description=entry.get("description", ""), + rationale=entry.get("rationale", ""), applies_to=entry.get("applies_to", []), examples=entry.get("examples", []), ) @@ -92,8 +92,8 @@ def load(directory: Path | None = None) -> list[Standard]: standards.append( Standard( domain=data.get("domain", yaml_file.stem), - category=data.get("category", str(yaml_file.parent.relative_to(target))), description=data.get("description", ""), + last_updated=data.get("last_updated", ""), principles=principles, ) ) @@ -102,15 +102,15 @@ def load(directory: Path | None = None) -> list[Standard]: return _cache -def format_for_prompt(agent_name: str | None = None, category: str | None = None) -> str: +def format_for_prompt(agent_name: str | None = None, domain: str | None = None) -> str: """Format standards as text for injection into agent system prompts.""" standards = load() if not standards: return "" filtered = standards - if category: - filtered = [s for s in filtered if s.category == category] + if domain: + filtered = [s for s in filtered if s.domain == domain] if not filtered: return "" @@ -135,6 +135,48 @@ def format_for_prompt(agent_name: str | None = None, category: str | None = None return "\n".join(sections) +def format_for_qa(iac_tool: str | None = None, layer: str = "infra") -> str: + """Format standards for QA context injection. + + Returns standards relevant to the stage's technology stack: + - IaC stages (core/infra/data): IaC-specific + universal coding/design + - App stages: all application + universal coding/design + + Parameters + ---------- + iac_tool: + ``"terraform"`` or ``"bicep"`` — selects IaC standards. + layer: + Stage layer — ``"core"``, ``"infra"``, ``"data"``, ``"app"``. + """ + standards = load() + if not standards: + return "" + + # Determine which domains to include + include_domains: set[str] = {"principles"} # always include coding/design + if layer in ("core", "infra", "data"): + if iac_tool == "terraform": + include_domains.add("terraform") + elif iac_tool == "bicep": + include_domains.add("bicep") + elif layer == "app": + include_domains.add("application") + + filtered = [s for s in standards if s.domain in include_domains] + if not filtered: + return "" + + sections: list[str] = ["## Applicable Standards\n"] + for standard in filtered: + sections.append(f"### {standard.domain}") + for p in standard.principles: + sections.append(f"- **[{p.id}]** {p.description}") + sections.append("") + + return "\n".join(sections) + + def reset_cache() -> None: """Clear the module-level cache (useful in tests).""" global _cache # noqa: PLW0603 diff --git a/azext_prototype/governance/standards/application/dotnet.yaml b/azext_prototype/governance/standards/application/dotnet.yaml index ec25f59..c8e02fd 100644 --- a/azext_prototype/governance/standards/application/dotnet.yaml +++ b/azext_prototype/governance/standards/application/dotnet.yaml @@ -1,81 +1,60 @@ -# .NET/C# application standards. -# -# These standards apply to generated .NET application code -# (APIs, Azure Functions, background workers). - -domain: .NET Application Standards -category: application -description: >- - Standards for generated .NET/C# application code, including project - structure, dependency management, Azure SDK patterns, and Azure Functions - isolated worker model requirements. - -principles: - - id: CS-001 - name: Use Azure SDK with DefaultAzureCredential - description: >- - Always use DefaultAzureCredential from Azure.Identity for - authenticating to Azure services. This works with managed - identity in Azure and developer credentials locally. - applies_to: - - app-developer - examples: - - "using Azure.Identity;" - - "var credential = new DefaultAzureCredential();" - - "Never pass connection strings when managed identity is available" - - - id: CS-002 - name: Complete Project Structure - description: >- - Every generated .NET app must include a .csproj file with all - NuGet PackageReferences, a Program.cs entry point, and all - model/DTO classes referenced by services. No file may reference - a type that is not defined in the generated output. - applies_to: - - app-developer - examples: - - "MyApp.csproj — project file with all PackageReferences" - - "Program.cs — entry point with DI registration" - - "Models/Project.cs — every referenced model class must exist" - - "If a service references 'ProjectDto', that class must be generated" - - - id: CS-003 - name: Azure Functions Isolated Worker Model - description: >- - All C# Azure Functions must target the .NET isolated worker model - using Microsoft.Azure.Functions.Worker (not the in-process model). - Must include host.json (version 2.0) and local.settings.json with - all required app settings. - applies_to: - - app-developer - examples: - - "Target net8.0 with Microsoft.Azure.Functions.Worker packages" - - "host.json with version 2.0 extensionBundle" - - "local.settings.json with FUNCTIONS_WORKER_RUNTIME = dotnet-isolated" - - "Program.cs with HostBuilder configuration" - - - id: CS-004 - name: Configuration via appsettings.json - description: >- - Use IConfiguration with appsettings.json for all configuration. - Never hardcode endpoints, connection strings, or secrets. Use - the Options pattern for strongly-typed settings. - applies_to: - - app-developer - examples: - - "builder.Configuration.AddJsonFile(\"appsettings.json\")" - - "services.Configure(config.GetSection(\"MyOptions\"))" - - "Never hardcode URLs, ports, or service endpoints" - - - id: CS-005 - name: Dependency Injection - description: >- - Use IServiceCollection for DI registration. All services, - repositories, and Azure SDK clients must be registered in - Program.cs. Use interface-based abstractions for testability. - applies_to: - - app-developer - examples: - - "builder.Services.AddSingleton();" - - "builder.Services.AddAzureClients(b => b.AddBlobServiceClient(...));" - - "Register all services used by controllers/functions in Program.cs" +kind: standard +domain: application +description: Standards for generated .NET/C# application code, including project structure, dependency management, Azure SDK + patterns, and Azure Functions isolated worker model requirements. +last_updated: '2026-04-04' +principles: +- id: STAN-CS-001 + description: 'Use Azure SDK with DefaultAzureCredential: Always use DefaultAzureCredential from Azure.Identity for authenticating + to Azure services. This works with managed identity in Azure and developer credentials locally.' + applies_to: + - csharp-developer + examples: + - using Azure.Identity; + - var credential = new DefaultAzureCredential(); + - Never pass connection strings when managed identity is available + rationale: DefaultAzureCredential provides seamless authentication across local dev and managed identity in production. +- id: STAN-CS-002 + description: 'Complete Project Structure: Every generated .NET app must include a .csproj file with all NuGet PackageReferences, + a Program.cs entry point, and all model/DTO classes referenced by services. No file may reference a type that is not + defined in the generated output.' + applies_to: + - csharp-developer + examples: + - MyApp.csproj — project file with all PackageReferences + - Program.cs — entry point with DI registration + - Models/Project.cs — every referenced model class must exist + - If a service references 'ProjectDto', that class must be generated + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-CS-003 + description: 'Azure Functions Isolated Worker Model: All C# Azure Functions must target the .NET isolated worker model using + Microsoft.Azure.Functions.Worker (not the in-process model). Must include host.json (version 2.0) and local.settings.json + with all required app settings.' + applies_to: + - csharp-developer + examples: + - Target net8.0 with Microsoft.Azure.Functions.Worker packages + - host.json with version 2.0 extensionBundle + - local.settings.json with FUNCTIONS_WORKER_RUNTIME = dotnet-isolated + - Program.cs with HostBuilder configuration + rationale: The isolated worker model provides better dependency isolation and .NET version flexibility. +- id: STAN-CS-004 + description: 'Configuration via appsettings.json: Use IConfiguration with appsettings.json for all configuration. Never + hardcode endpoints, connection strings, or secrets. Use the Options pattern for strongly-typed settings.' + applies_to: + - csharp-developer + examples: + - builder.Configuration.AddJsonFile("appsettings.json") + - services.Configure(config.GetSection("MyOptions")) + - Never hardcode URLs, ports, or service endpoints + rationale: Externalized configuration supports environment-specific settings without code changes. +- id: STAN-CS-005 + description: 'Dependency Injection: Use IServiceCollection for DI registration. All services, repositories, and Azure SDK + clients must be registered in Program.cs. Use interface-based abstractions for testability.' + applies_to: + - csharp-developer + examples: + - builder.Services.AddSingleton(); + - builder.Services.AddAzureClients(b => b.AddBlobServiceClient(...)); + - Register all services used by controllers/functions in Program.cs + rationale: Pinned dependencies ensure reproducible builds and prevent unexpected breaking changes. diff --git a/azext_prototype/governance/standards/application/generic.yaml b/azext_prototype/governance/standards/application/generic.yaml new file mode 100644 index 0000000..9479d08 --- /dev/null +++ b/azext_prototype/governance/standards/application/generic.yaml @@ -0,0 +1,80 @@ +kind: standard +domain: application +description: Language-agnostic application standards for the generic app-developer agent, covering project structure, + Azure SDK patterns, configuration, and code quality applicable to any language not handled by a dedicated developer. +last_updated: '2026-04-05' +principles: +- id: STAN-APP-001 + description: 'Use Azure SDK with DefaultAzureCredential: Always use the platform-appropriate DefaultAzureCredential + for authenticating to Azure services. This works with managed identity in Azure and developer credentials locally. + Never pass connection strings or access keys when managed identity is available.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Use the official Azure Identity library for your language + - Initialize a DefaultAzureCredential instance at application startup + - Pass the credential to all Azure SDK clients + - Never embed secrets, keys, or connection strings in source code + rationale: DefaultAzureCredential provides seamless authentication across local dev and managed identity in production. +- id: STAN-APP-002 + description: 'Complete Project Structure: Every generated application must include a dependency manifest (package.json, + build.gradle, go.mod, Cargo.toml, etc.), an entry point file, and all model/DTO classes referenced by services. + No file may reference a type that is not defined in the generated output.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Dependency manifest with all required packages and pinned versions + - Entry point file with service initialization and configuration + - All referenced types must be defined in the generated output + - Include a Dockerfile for containerized deployment + rationale: Complete outputs enable downstream stages to build and deploy without missing dependencies. +- id: STAN-APP-003 + description: 'Configuration via Environment Variables: Use environment variables for all configuration. Never hardcode + service URLs, ports, connection strings, or feature flags. Include a .env.example file listing all required + environment variables with descriptions.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Read configuration from environment variables at startup + - Use a configuration library appropriate for your language + - Include .env.example documenting every required variable + - Never hardcode endpoints, ports, or service names + rationale: Externalized configuration supports environment-specific settings without code changes. +- id: STAN-APP-004 + description: 'Health Check Endpoints: All web applications and APIs must expose a /healthz endpoint that returns + HTTP 200 when the service is ready. Background workers should implement health monitoring appropriate + to their platform (e.g., liveness probes for Kubernetes).' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - GET /healthz returning 200 OK with {"status":"healthy"} + - Optionally check downstream dependencies in the health response + - Include readiness and liveness endpoints for container orchestrators + rationale: Health check endpoints enable load balancers and orchestrators to route traffic correctly. +- id: STAN-APP-005 + description: 'Structured Logging: Use structured logging with key-value pairs instead of string interpolation. + Log levels must be used consistently: ERROR for failures requiring attention, WARN for degraded conditions, + INFO for operational events, DEBUG for troubleshooting.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Use the platform-standard logging framework (not print/console.log) + - Include correlation IDs in log entries for distributed tracing + - Log at INFO level for request start/end, ERROR for unhandled exceptions + - Never log secrets, tokens, or personally identifiable information + rationale: Structured logging enables centralized log aggregation, querying, and alerting in Azure Monitor. diff --git a/azext_prototype/governance/standards/application/python.yaml b/azext_prototype/governance/standards/application/python.yaml index c530c1e..ea6b88f 100644 --- a/azext_prototype/governance/standards/application/python.yaml +++ b/azext_prototype/governance/standards/application/python.yaml @@ -1,75 +1,55 @@ -# Python application standards. -# -# These standards apply to generated Python application code -# (APIs, functions, background workers). - -domain: Python Application Standards -category: application -description: >- - Standards for generated Python application code, including project - structure, dependency management, and Azure SDK patterns. - -principles: - - id: PY-001 - name: Use Azure SDK with DefaultAzureCredential - description: >- - Always use DefaultAzureCredential from azure-identity for - authenticating to Azure services. This works with managed - identity in Azure and developer credentials locally. - applies_to: - - app-developer - examples: - - "from azure.identity import DefaultAzureCredential" - - "credential = DefaultAzureCredential()" - - "Never pass connection strings when managed identity is available" - - - id: PY-002 - name: Project Structure - description: >- - Python projects must have a clear structure: src/ for application - code, tests/ for tests, requirements.txt or pyproject.toml for - dependencies. Use packages (directories with __init__.py) for - logical grouping. - applies_to: - - app-developer - examples: - - "src/app/ — application package" - - "src/app/main.py — entry point" - - "src/app/routes/ — API route handlers" - - "src/app/services/ — business logic" - - "tests/ — test files" - - - id: PY-003 - name: Configuration via Environment Variables - description: >- - Use environment variables for all configuration (loaded via - os.environ or a settings class). Never hardcode service URLs, - ports, or feature flags. - applies_to: - - app-developer - examples: - - "import os; port = int(os.environ.get('PORT', 8080))" - - "Use pydantic Settings class for type-safe config" - - - id: PY-004 - name: Async for I/O-Bound Operations - description: >- - Use async/await for HTTP handlers, database queries, and - external API calls. Synchronous I/O blocks the event loop - and reduces throughput. - applies_to: - - app-developer - examples: - - "async def get_items(db: AsyncSession) -> list[Item]:" - - "Use aiohttp or httpx for async HTTP clients" - - - id: PY-005 - name: Type Annotations - description: >- - Use type annotations on all function signatures and return types. - This enables IDE support, documentation, and static analysis. - applies_to: - - app-developer - examples: - - "def get_user(user_id: str) -> User | None:" - - "async def create_order(order: OrderCreate) -> OrderResponse:" +kind: standard +domain: application +description: Standards for generated Python application code, including project structure, dependency management, and Azure + SDK patterns. +last_updated: '2026-04-04' +principles: +- id: STAN-PY-001 + description: 'Use Azure SDK with DefaultAzureCredential: Always use DefaultAzureCredential from azure-identity for authenticating + to Azure services. This works with managed identity in Azure and developer credentials locally.' + applies_to: + - python-developer + examples: + - from azure.identity import DefaultAzureCredential + - credential = DefaultAzureCredential() + - Never pass connection strings when managed identity is available + rationale: DefaultAzureCredential provides seamless authentication across local dev and managed identity in production. +- id: STAN-PY-002 + description: 'Project Structure: Python projects must have a clear structure: src/ for application code, tests/ for tests, + requirements.txt or pyproject.toml for dependencies. Use packages (directories with __init__.py) for logical grouping.' + applies_to: + - python-developer + examples: + - src/app/ — application package + - src/app/main.py — entry point + - src/app/routes/ — API route handlers + - src/app/services/ — business logic + - tests/ — test files + rationale: Pinned dependencies ensure reproducible builds and prevent unexpected breaking changes. +- id: STAN-PY-003 + description: 'Configuration via Environment Variables: Use environment variables for all configuration (loaded via os.environ + or a settings class). Never hardcode service URLs, ports, or feature flags.' + applies_to: + - python-developer + examples: + - import os; port = int(os.environ.get('PORT', 8080)) + - Use pydantic Settings class for type-safe config + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-PY-004 + description: 'Async for I/O-Bound Operations: Use async/await for HTTP handlers, database queries, and external API calls. Synchronous + I/O blocks the event loop and reduces throughput.' + applies_to: + - python-developer + examples: + - 'async def get_items(db: AsyncSession) -> list[Item]:' + - Use aiohttp or httpx for async HTTP clients + rationale: Following established standards ensures consistency, quality, and maintainability across the codebase. +- id: STAN-PY-005 + description: 'Type Annotations: Use type annotations on all function signatures and return types. This enables IDE support, + documentation, and static analysis.' + applies_to: + - python-developer + examples: + - 'def get_user(user_id: str) -> User | None:' + - 'async def create_order(order: OrderCreate) -> OrderResponse:' + rationale: Following established standards ensures consistency, quality, and maintainability across the codebase. diff --git a/azext_prototype/governance/standards/bicep/modules.yaml b/azext_prototype/governance/standards/bicep/modules.yaml deleted file mode 100644 index 0df60ea..0000000 --- a/azext_prototype/governance/standards/bicep/modules.yaml +++ /dev/null @@ -1,113 +0,0 @@ -# Bicep module structure standards. -# -# These standards define how Bicep templates and modules should be -# organized for consistency across all generated IaC. - -domain: Bicep Module Structure -category: bicep -description: >- - Standards for Bicep template layout, parameter naming, and resource - organization that all bicep-agent output must follow. - -principles: - - id: BCP-001 - name: Standard File Layout - description: >- - Bicep templates must follow a consistent ordering: targetScope - (if needed), parameters, variables, resources, modules, outputs. - Use separate .bicep files for reusable modules. - applies_to: - - bicep-agent - examples: - - "main.bicep — orchestration template that calls modules" - - "modules/appService.bicep — reusable App Service module" - - "modules/networking.bicep — reusable networking module" - - - id: BCP-002 - name: Parameter Conventions - description: >- - All parameters must have @description decorators and type - annotations. Use camelCase for parameter names (Bicep convention). - Provide @allowed decorators for constrained values. - applies_to: - - bicep-agent - examples: - - "@description('Azure region for all resources') param location string = resourceGroup().location" - - "@allowed(['dev','staging','prod']) param environment string" - - - id: BCP-003 - name: Module Composition - description: >- - Use Bicep modules for logical grouping of related resources. - The main.bicep file should orchestrate modules, not define - resources directly (except resource groups at subscription scope). - applies_to: - - bicep-agent - examples: - - "module networking 'modules/networking.bicep' = { ... }" - - "module compute 'modules/compute.bicep' = { ... }" - - - id: BCP-004 - name: Resource Naming via Variables - description: >- - Define resource names in variables using a consistent naming - pattern. Never hardcode resource names in resource blocks. - applies_to: - - bicep-agent - examples: - - "var rgName = 'rg-${project}-${environment}'" - - "var kvName = 'kv-${project}-${take(uniqueString(resourceGroup().id), 6)}'" - - - id: BCP-005 - name: Output Important Values - description: >- - Output resource IDs, endpoints, and principal IDs that - downstream modules or deployment scripts will need. - Use @description decorators on outputs. - applies_to: - - bicep-agent - examples: - - "@description('App Service default hostname') output appUrl string = app.properties.defaultHostName" - - "@description('Managed identity principal ID') output principalId string = app.identity.principalId" - - - id: BCP-006 - name: Cross-Stage Dependencies via Parameters - description: >- - Multi-stage deployments MUST pass prior-stage resource references - as parameters. NEVER hardcode resource names, IDs, or keys from - other stages. Use the existing keyword to reference resources - created in prior stages, with their names provided via parameters - populated from prior stage deployment outputs. - applies_to: - - bicep-agent - - cloud-architect - examples: - - "@description('Resource group from Stage 1') param foundationRgName string" - - "resource rg 'Microsoft.Resources/resourceGroups@2023-07-01' existing = { name: foundationRgName }" - - - id: BCP-007 - name: Complete and Robust deploy.sh - description: >- - Every stage MUST include a deploy.sh that is syntactically complete - and runnable. It must use set -euo pipefail, verify Azure login, - run az deployment group create, capture outputs to JSON, and include - error handling via trap. NEVER truncate the script. - applies_to: - - bicep-agent - examples: - - "az deployment group create --resource-group $RG --template-file main.bicep --parameters main.bicepparam" - - "az deployment group show --name $DEPLOYMENT --query properties.outputs > stage-N-outputs.json" - - - id: BCP-008 - name: Companion Resources for Disabled Auth - description: >- - When disabling local/key-based auth on any service, the SAME stage - MUST also create: (1) a user-assigned managed identity, (2) RBAC - role assignments, (3) output the identity clientId and principalId. - Without these, applications cannot authenticate. - applies_to: - - bicep-agent - - cloud-architect - examples: - - "resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { ... }" - - "resource rbac 'Microsoft.Authorization/roleAssignments@2022-04-01' = { ... }" diff --git a/azext_prototype/governance/standards/iac/__init__.py b/azext_prototype/governance/standards/iac/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/governance/standards/iac/bicep.yaml b/azext_prototype/governance/standards/iac/bicep.yaml new file mode 100644 index 0000000..520c4c7 --- /dev/null +++ b/azext_prototype/governance/standards/iac/bicep.yaml @@ -0,0 +1,84 @@ +kind: standard +domain: bicep +description: Standards for Bicep template layout, parameter naming, and resource organization that all bicep-agent output + must follow. +last_updated: '2026-04-04' +principles: +- id: STAN-BCP-001 + description: 'Standard File Layout: Bicep templates must follow a consistent ordering: targetScope (if needed), parameters, + variables, resources, modules, outputs. Use separate .bicep files for reusable modules.' + applies_to: + - bicep-agent + examples: + - main.bicep — orchestration template that calls modules + - modules/appService.bicep — reusable App Service module + - modules/networking.bicep — reusable networking module + rationale: Consistent file organization makes code reviewable and prevents merge conflicts across stages. +- id: STAN-BCP-002 + description: 'Parameter Conventions: All parameters must have @description decorators and type annotations. Use camelCase + for parameter names (Bicep convention). Provide @allowed decorators for constrained values.' + applies_to: + - bicep-agent + examples: + - '@description(''Azure region for all resources'') param location string = resourceGroup().location' + - '@allowed([''dev'',''staging'',''prod'']) param environment string' + rationale: Well-typed parameters with constraints prevent invalid deployments at plan time. +- id: STAN-BCP-003 + description: 'Module Composition: Use Bicep modules for logical grouping of related resources. The main.bicep file should + orchestrate modules, not define resources directly (except resource groups at subscription scope).' + applies_to: + - bicep-agent + examples: + - module networking 'modules/networking.bicep' = { ... } + - module compute 'modules/compute.bicep' = { ... } + rationale: Modular Bicep templates promote reuse and simplify testing of individual components. +- id: STAN-BCP-004 + description: 'Resource Naming via Variables: Define resource names in variables using a consistent naming pattern. Never + hardcode resource names in resource blocks.' + applies_to: + - bicep-agent + examples: + - var rgName = 'rg-${project}-${environment}' + - var kvName = 'kv-${project}-${take(uniqueString(resourceGroup().id), 6)}' + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-BCP-005 + description: 'Output Important Values: Output resource IDs, endpoints, and principal IDs that downstream modules or deployment + scripts will need. Use @description decorators on outputs.' + applies_to: + - bicep-agent + examples: + - '@description(''App Service default hostname'') output appUrl string = app.properties.defaultHostName' + - '@description(''Managed identity principal ID'') output principalId string = app.identity.principalId' + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-BCP-006 + description: 'Cross-Stage Dependencies via Parameters: Multi-stage deployments MUST pass prior-stage resource references + as parameters. NEVER hardcode resource names, IDs, or keys from other stages. Use the existing keyword to reference resources + created in prior stages, with their names provided via parameters populated from prior stage deployment outputs.' + applies_to: + - bicep-agent + - cloud-architect + examples: + - '@description(''Resource group from Stage 1'') param foundationRgName string' + - 'resource rg ''Microsoft.Resources/resourceGroups@2023-07-01'' existing = { name: foundationRgName }' + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-BCP-007 + description: 'Complete and Robust deploy.sh: Every stage MUST include a deploy.sh that is syntactically complete and runnable. + It must use set -euo pipefail, verify Azure login, run az deployment group create, capture outputs to JSON, and include + error handling via trap. NEVER truncate the script.' + applies_to: + - bicep-agent + examples: + - az deployment group create --resource-group $RG --template-file main.bicep --parameters main.bicepparam + - az deployment group show --name $DEPLOYMENT --query properties.outputs > stage-N-outputs.json + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-BCP-008 + description: 'Companion Resources for Disabled Auth: When disabling local/key-based auth on any service, the SAME stage + MUST also create: (1) a user-assigned managed identity, (2) RBAC role assignments, (3) output the identity clientId and + principalId. Without these, applications cannot authenticate.' + applies_to: + - bicep-agent + - cloud-architect + examples: + - resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { ... } + - resource rbac 'Microsoft.Authorization/roleAssignments@2022-04-01' = { ... } + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. diff --git a/azext_prototype/governance/standards/iac/terraform.yaml b/azext_prototype/governance/standards/iac/terraform.yaml new file mode 100644 index 0000000..4928473 --- /dev/null +++ b/azext_prototype/governance/standards/iac/terraform.yaml @@ -0,0 +1,123 @@ +kind: standard +domain: terraform +description: Standards for Terraform module layout, variable naming, and resource organization that all terraform-agent output + must follow. +last_updated: '2026-04-04' +principles: +- id: STAN-TF-001 + description: 'Standard File Layout: Every Terraform module must use the standard file layout: main.tf (resources only), + variables.tf (inputs), outputs.tf (outputs), locals.tf (computed values), providers.tf (terraform {}, required_providers, + provider config, and backend). The terraform {} block — including required_providers — MUST appear in exactly ONE file + (providers.tf). Do NOT create a separate versions.tf. main.tf must NOT contain terraform {} or provider {} blocks. Additional + files are allowed for complex modules but must be logically named (e.g., networking.tf, iam.tf).' + applies_to: + - terraform-agent + examples: + - main.tf — resource definitions only (no terraform {} or provider {} blocks) + - variables.tf — all input variable declarations with descriptions and types + - outputs.tf — all output value declarations + - locals.tf — computed local values and naming conventions + - providers.tf — terraform {}, required_providers, backend, and provider configuration (ONE file, never duplicated) + rationale: Consistent file organization makes code reviewable and prevents merge conflicts across stages. +- id: STAN-TF-002 + description: 'Variable Conventions: All variables must have a description and a type constraint. Use snake_case for variable + names. Provide defaults for optional values. Use validation blocks for constrained inputs.' + applies_to: + - terraform-agent + examples: + - variable "location" { type = string; description = "Azure region" } + - Use validation blocks for SKU names, IP ranges, etc. + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-TF-003 + description: 'Resource Naming via Variables or Locals: Resource names should come from variables with defaults set + to the deployment plan computed_name, or from locals that derive names from project variables. Variable defaults + from the deployment plan (e.g., "pi-rg-worker-dev-wus3") are acceptable — the naming strategy already computed + them. Do NOT force computed_name values into locals when they are already correct as variable defaults.' + applies_to: + - terraform-agent + examples: + - variable "resource_group_name" { default = "pi-rg-worker-dev-wus3" } + - locals { identity_name = "${var.zone_prefix}-id-worker-${var.environment}-${var.region_short}" } + - resource "azapi_resource" "resource_group" { name = var.resource_group_name } + rationale: The CLI naming module computes resource names per the project naming strategy. Variable defaults carry + these computed names and are overridable at deploy time. +- id: STAN-TF-004 + description: 'One Resource Type Per File for Complex Modules: When a module manages more than 5 resources, split logically + related resources into separate files (e.g., networking.tf for subnets and NSGs, iam.tf for role assignments).' + applies_to: + - terraform-agent + examples: + - networking.tf — VNet, subnets, NSGs, route tables + - iam.tf — role assignments, managed identities + - monitoring.tf — diagnostic settings, alerts + rationale: Modular Bicep templates promote reuse and simplify testing of individual components. +- id: STAN-TF-005 + description: 'Use Data Sources for Existing Resources: Reference existing resources (resource groups, VNets, identities) + via data sources, not by hardcoding IDs. Pass resource IDs as variables only when the resource is managed outside the + module.' + applies_to: + - terraform-agent + examples: + - data "azapi_client_config" "current" {} for tenant/subscription IDs + - data "azapi_resource" "existing_rg" { type = "Microsoft.Resources/resourceGroups@2024-03-01"; name = var.rg_name } + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-TF-006 + description: 'Cross-Stage Dependencies via Remote State: Multi-stage deployments MUST use terraform_remote_state data sources + to read outputs from prior stages. NEVER hardcode resource names, IDs, or keys that belong to another stage. Each stage + reads what it needs from prior stage state files and passes values via data.terraform_remote_state..outputs..' + applies_to: + - terraform-agent + - cloud-architect + examples: + - data "terraform_remote_state" "stage1" { backend = "azurerm"; config = { key = "stage1.tfstate" } } + - data "azapi_resource" "resource_group" { type = "Microsoft.Resources/resourceGroups@2024-03-01"; name = data.terraform_remote_state.stage1.outputs.resource_group_name } + rationale: Proper state management prevents cross-stage conflicts and ensures reliable deployments. +- id: STAN-TF-007 + description: 'Consistent Backend Configuration: Backend configuration must be consistent across all stages. For POC deployments, + use local state (no backend block or backend "local" with a path). For production, use backend "azurerm" with ALL required + fields populated with literal values (resource_group_name, storage_account_name, container_name, key). NEVER use variable + references (var.*) in backend config — Terraform does not support them. NEVER leave required backend fields empty. If + using remote backend, all stages must reference the same storage account and container, differing only in key.' + applies_to: + - terraform-agent + examples: + - 'POC: backend "local" {} — default terraform.tfstate in stage directory' + - 'Cross-stage ref: ../stage-1-managed-identity/terraform.tfstate' + - 'Production: backend "azurerm" { resource_group_name = "terraform-state-rg"; storage_account_name = "tfstate12345"; container_name + = "tfstate"; key = "stage1.tfstate" }' + rationale: Proper state management prevents cross-stage conflicts and ensures reliable deployments. +- id: STAN-TF-008 + description: 'Complete Stage Outputs: Every stage''s outputs.tf MUST export all resource names, IDs, and endpoints that + ANY downstream stage or application needs. At minimum: resource group name(s), managed identity client_id/principal_id, + service endpoints, workspace IDs. NEVER output sensitive values (keys, connection strings) — if local auth is disabled, + omit keys entirely.' + applies_to: + - terraform-agent + examples: + - output "resource_group_name" { value = azapi_resource.resource_group.name } + - output "managed_identity_client_id" { value = azapi_resource.managed_identity.output.properties.clientId } + - '# Do NOT output primary_key when local auth is disabled' + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-TF-009 + description: 'Complete and Robust deploy.sh: Every stage MUST include a deploy.sh that is syntactically complete and runnable. + It must use set -euo pipefail, include Azure login verification, run terraform init/plan/apply, export outputs to JSON, + and include error handling via trap. NEVER truncate the script or leave strings unclosed.' + applies_to: + - terraform-agent + examples: + - '#!/bin/bash\nset -euo pipefail\ntrap ''echo Deploy failed'' ERR' + - terraform output -json > stage-1-outputs.json + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. +- id: STAN-TF-010 + description: 'Companion Resources for Disabled Auth: When disabling local/key-based authentication on any service (local_authentication_disabled + = true, shared_access_key_enabled = false), the SAME stage MUST also create: (1) a user-assigned managed identity, (2) + RBAC role assignments granting that identity access, (3) outputs for the identity''s client_id and principal_id. Without + these companion resources, applications cannot authenticate and the deployment is broken.' + applies_to: + - terraform-agent + - cloud-architect + examples: + - resource "azapi_resource" "managed_identity" { type = "Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31"; ... } + - resource "azapi_resource" "cosmosdb_role_assignment" { type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15"; + body = { properties = { principalId = azapi_resource.managed_identity.output.properties.principalId } } } + rationale: Complete outputs enable downstream stages to reference resources without hardcoding. diff --git a/azext_prototype/governance/standards/principles/coding.yaml b/azext_prototype/governance/standards/principles/coding.yaml index aadb0e3..55a6cda 100644 --- a/azext_prototype/governance/standards/principles/coding.yaml +++ b/azext_prototype/governance/standards/principles/coding.yaml @@ -1,73 +1,67 @@ -# Coding standards — code quality and structure. -# -# These apply specifically to application code generation -# (app-developer agent) and IaC generation (terraform/bicep agents). - -domain: Coding Standards -category: principles -description: >- - Code quality standards for generated application and infrastructure code. - -principles: - - id: CODE-001 - name: Meaningful Names - description: >- - Use descriptive, intention-revealing names for variables, functions, - resources, and modules. Avoid abbreviations unless they are - universally understood (e.g., HTTP, URL, ID). - applies_to: - - terraform-agent - - bicep-agent - - app-developer - examples: - - "Use 'storage_account' not 'sa'; 'container_registry' not 'cr'" - - "Use 'get_user_by_email()' not 'get_u()'" - - - id: CODE-002 - name: Small Functions - description: >- - Functions should be short and focused. If a function exceeds - roughly 30 lines, it likely does too much and should be split. - applies_to: - - app-developer - examples: - - "Split 'process_order()' into 'validate_order()', 'calculate_total()', 'save_order()'" - - - id: CODE-003 - name: Error Handling at Boundaries - description: >- - Handle errors at system boundaries (user input, external APIs, - file I/O). Internal code should trust its contracts. - applies_to: - - app-developer - examples: - - "Validate API request payloads at the controller layer, not in every function" - - "Wrap external HTTP calls in try/except, not internal method calls" - - - id: CODE-004 - name: Consistent Module Structure - description: >- - Terraform modules should follow a consistent file layout: - main.tf, variables.tf, outputs.tf, locals.tf, providers.tf. - Bicep modules should separate parameters, resources, and outputs. - applies_to: - - terraform-agent - - bicep-agent - examples: - - "Terraform: variables.tf for inputs, main.tf for resources, outputs.tf for outputs" - - "Bicep: param block at top, resource declarations, output block at bottom" - - - id: CODE-005 - name: Parameterize, Don't Hard-Code - description: >- - All environment-specific values (names, regions, SKUs, IP ranges) - must be parameterized via variables or parameters. Never embed - environment-specific values in resource definitions. - applies_to: - - terraform-agent - - bicep-agent - - app-developer - examples: - - "Terraform: use var.location not 'eastus' in resource blocks" - - "Bicep: use param location string not 'eastus'" - - "Application: use environment variables or config files, not inline strings" +kind: standard +domain: principles +description: Code quality standards for generated application and infrastructure code. +last_updated: '2026-04-04' +principles: +- id: STAN-CODE-001 + description: 'Meaningful Names: Use descriptive, intention-revealing names for variables, functions, resources, and modules. Avoid + abbreviations unless they are universally understood (e.g., HTTP, URL, ID).' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Use 'storage_account' not 'sa'; 'container_registry' not 'cr' + - Use 'get_user_by_email()' not 'get_u()' + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-CODE-002 + description: 'Small Functions: Functions should be short and focused. If a function exceeds roughly 30 lines, it likely + does too much and should be split.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Split 'process_order()' into 'validate_order()', 'calculate_total()', 'save_order()' + rationale: The isolated worker model provides better dependency isolation and .NET version flexibility. +- id: STAN-CODE-003 + description: 'Error Handling at Boundaries: Handle errors at system boundaries (user input, external APIs, file I/O). Internal + code should trust its contracts.' + applies_to: + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - Validate API request payloads at the controller layer, not in every function + - Wrap external HTTP calls in try/except, not internal method calls + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-CODE-004 + description: 'Consistent Module Structure: Terraform modules should follow a consistent file layout: main.tf, variables.tf, + outputs.tf, locals.tf, providers.tf. Bicep modules should separate parameters, resources, and outputs.' + applies_to: + - terraform-agent + - bicep-agent + examples: + - 'Terraform: variables.tf for inputs, main.tf for resources, outputs.tf for outputs' + - 'Bicep: param block at top, resource declarations, output block at bottom' + rationale: Consistent file organization makes code reviewable and prevents merge conflicts across stages. +- id: STAN-CODE-005 + description: 'Parameterize, Don''t Hard-Code: All environment-specific values (names, regions, SKUs, IP ranges) must be + parameterized via variables or parameters. Never embed environment-specific values in resource definitions.' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - 'Terraform: use var.location not ''eastus'' in resource blocks' + - 'Bicep: use param location string not ''eastus''' + - 'Application: use environment variables or config files, not inline strings' + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. diff --git a/azext_prototype/governance/standards/principles/design.yaml b/azext_prototype/governance/standards/principles/design.yaml index 5b439fb..eba81bd 100644 --- a/azext_prototype/governance/standards/principles/design.yaml +++ b/azext_prototype/governance/standards/principles/design.yaml @@ -1,84 +1,78 @@ -# Design principles — universal standards for all generated code and IaC. -# -# These principles apply to all agents that generate code, whether -# application code (Python, .NET, Node.js) or infrastructure-as-code -# (Terraform, Bicep). - -domain: Design Principles -category: principles -description: >- - Universal design principles that all generated code and infrastructure - must follow. These are not suggestions — they are standards. - -principles: - - id: DES-001 - name: Single Responsibility - description: >- - Every function, method, class, and module must have exactly one - responsibility. If a function does more than one thing, split it. - applies_to: - - terraform-agent - - bicep-agent - - app-developer - - cloud-architect - examples: - - "Terraform: one resource per module when the resource has complex configuration" - - "Application: a function that fetches data should not also format it for display" - - "Bicep: separate networking resources from compute resources into distinct modules" - - - id: DES-002 - name: DRY (Don't Repeat Yourself) - description: >- - Extract repeated logic into shared functions, modules, or variables. - Duplication is acceptable only when the duplicated code serves - genuinely different purposes that may evolve independently. - applies_to: - - terraform-agent - - bicep-agent - - app-developer - examples: - - "Terraform: use locals and variables instead of repeating values" - - "Application: extract common HTTP client setup into a shared utility" - - "Bicep: use modules for repeated resource patterns" - - - id: DES-003 - name: Open/Closed Principle - description: >- - Modules and classes should be open for extension but closed for - modification. Use variables, parameters, and composition to allow - customization without changing the core implementation. - applies_to: - - terraform-agent - - bicep-agent - - app-developer - examples: - - "Terraform: use variable maps for optional features instead of hard-coded conditionals" - - "Application: use dependency injection instead of hard-coded implementations" - - - id: DES-004 - name: Least Privilege - description: >- - Grant only the minimum permissions required. Every role assignment, - network rule, and access grant should be as narrow as possible. - applies_to: - - terraform-agent - - bicep-agent - - cloud-architect - - security-reviewer - examples: - - "Use 'Storage Blob Data Reader' instead of 'Contributor' for read-only access" - - "Scope role assignments to the specific resource, not the resource group" - - - id: DES-005 - name: Explicit Over Implicit - description: >- - Be explicit about configuration, dependencies, and behavior. - Avoid relying on defaults that may change or on implicit ordering. - applies_to: - - terraform-agent - - bicep-agent - - app-developer - examples: - - "Terraform: always set explicit depends_on when resource ordering matters" - - "Bicep: declare parameter defaults explicitly" - - "Application: use explicit type annotations and return types" +kind: standard +domain: principles +description: Universal design principles that all generated code and infrastructure must follow. These are not suggestions + — they are standards. +last_updated: '2026-04-04' +principles: +- id: STAN-DES-001 + description: 'Single Responsibility: Every function, method, class, and module must have exactly one responsibility. If + a function does more than one thing, split it.' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + - cloud-architect + examples: + - 'Terraform: one resource per module when the resource has complex configuration' + - 'Application: a function that fetches data should not also format it for display' + - 'Bicep: separate networking resources from compute resources into distinct modules' + rationale: Modular Bicep templates promote reuse and simplify testing of individual components. +- id: STAN-DES-002 + description: 'DRY (Don''t Repeat Yourself): Extract repeated logic into shared functions, modules, or variables. Duplication + is acceptable only when the duplicated code serves genuinely different purposes that may evolve independently.' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - 'Terraform: use locals and variables instead of repeating values' + - 'Application: extract common HTTP client setup into a shared utility' + - 'Bicep: use modules for repeated resource patterns' + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-DES-003 + description: 'Open/Closed Principle: Modules and classes should be open for extension but closed for modification. Use + variables, parameters, and composition to allow customization without changing the core implementation.' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - 'Terraform: use variable maps for optional features instead of hard-coded conditionals' + - 'Application: use dependency injection instead of hard-coded implementations' + rationale: Parameterized configurations allow reuse across environments and prevent hardcoded values. +- id: STAN-DES-004 + description: 'Least Privilege: Grant only the minimum permissions required. Every role assignment, network rule, and access + grant should be as narrow as possible.' + applies_to: + - terraform-agent + - bicep-agent + - cloud-architect + - security-architect + examples: + - Use 'Storage Blob Data Reader' instead of 'Contributor' for read-only access + - Scope role assignments to the specific resource, not the resource group + rationale: Following established standards ensures consistency, quality, and maintainability across the codebase. +- id: STAN-DES-005 + description: 'Explicit Over Implicit: Be explicit about configuration, dependencies, and behavior. Avoid relying on defaults + that may change or on implicit ordering.' + applies_to: + - terraform-agent + - bicep-agent + - app-developer + - csharp-developer + - python-developer + - react-developer + examples: + - 'Terraform: always set explicit depends_on when resource ordering matters' + - 'Bicep: declare parameter defaults explicitly' + - 'Application: use explicit type annotations and return types' + rationale: Externalized configuration supports environment-specific settings without code changes. diff --git a/azext_prototype/governance/standards/terraform/modules.yaml b/azext_prototype/governance/standards/terraform/modules.yaml deleted file mode 100644 index 7246044..0000000 --- a/azext_prototype/governance/standards/terraform/modules.yaml +++ /dev/null @@ -1,159 +0,0 @@ -# Terraform module structure standards. -# -# These standards define how Terraform modules should be organized -# and structured for consistency across all generated IaC. - -domain: Terraform Module Structure -category: terraform -description: >- - Standards for Terraform module layout, variable naming, and resource - organization that all terraform-agent output must follow. - -principles: - - id: TF-001 - name: Standard File Layout - description: >- - Every Terraform module must use the standard file layout: - main.tf (resources only), variables.tf (inputs), outputs.tf (outputs), - locals.tf (computed values), providers.tf (terraform {}, required_providers, - provider config, and backend). The terraform {} block — including - required_providers — MUST appear in exactly ONE file (providers.tf). - Do NOT create a separate versions.tf. main.tf must NOT contain - terraform {} or provider {} blocks. Additional files are allowed - for complex modules but must be logically named (e.g., networking.tf, - iam.tf). - applies_to: - - terraform-agent - examples: - - "main.tf — resource definitions only (no terraform {} or provider {} blocks)" - - "variables.tf — all input variable declarations with descriptions and types" - - "outputs.tf — all output value declarations" - - "locals.tf — computed local values and naming conventions" - - "providers.tf — terraform {}, required_providers, backend, and provider configuration (ONE file, never duplicated)" - - - id: TF-002 - name: Variable Conventions - description: >- - All variables must have a description and a type constraint. - Use snake_case for variable names. Provide defaults for optional - values. Use validation blocks for constrained inputs. - applies_to: - - terraform-agent - examples: - - "variable \"location\" { type = string; description = \"Azure region\" }" - - "Use validation blocks for SKU names, IP ranges, etc." - - - id: TF-003 - name: Resource Naming via Locals - description: >- - Define resource names in a locals block using a consistent naming - pattern. Never hardcode resource names in resource blocks. - applies_to: - - terraform-agent - examples: - - "locals { rg_name = \"rg-${var.project}-${var.environment}\" }" - - "resource \"azurerm_resource_group\" \"main\" { name = local.rg_name }" - - - id: TF-004 - name: One Resource Type Per File for Complex Modules - description: >- - When a module manages more than 5 resources, split logically - related resources into separate files (e.g., networking.tf for - subnets and NSGs, iam.tf for role assignments). - applies_to: - - terraform-agent - examples: - - "networking.tf — VNet, subnets, NSGs, route tables" - - "iam.tf — role assignments, managed identities" - - "monitoring.tf — diagnostic settings, alerts" - - - id: TF-005 - name: Use Data Sources for Existing Resources - description: >- - Reference existing resources (resource groups, VNets, identities) - via data sources, not by hardcoding IDs. Pass resource IDs as - variables only when the resource is managed outside the module. - applies_to: - - terraform-agent - examples: - - "data \"azurerm_client_config\" \"current\" {} for tenant/subscription IDs" - - "data \"azurerm_resource_group\" \"existing\" { name = var.rg_name }" - - - id: TF-006 - name: Cross-Stage Dependencies via Remote State - description: >- - Multi-stage deployments MUST use terraform_remote_state data sources - to read outputs from prior stages. NEVER hardcode resource names, - IDs, or keys that belong to another stage. Each stage reads what it - needs from prior stage state files and passes values via - data.terraform_remote_state..outputs.. - applies_to: - - terraform-agent - - cloud-architect - examples: - - "data \"terraform_remote_state\" \"stage1\" { backend = \"azurerm\"; config = { key = \"stage1.tfstate\" } }" - - "data \"azurerm_resource_group\" \"main\" { name = data.terraform_remote_state.stage1.outputs.resource_group_name }" - - - id: TF-007 - name: Consistent Backend Configuration - description: >- - Backend configuration must be consistent across all stages. For POC - deployments, use local state (no backend block or backend "local" with - a path). For production, use backend "azurerm" with ALL required - fields populated with literal values (resource_group_name, - storage_account_name, container_name, key). NEVER use variable - references (var.*) in backend config — Terraform does not support - them. NEVER leave required backend fields empty. If using remote - backend, all stages must reference the same storage account and - container, differing only in key. - applies_to: - - terraform-agent - examples: - - "POC: omit backend block entirely (local state by default)" - - "POC multi-stage: backend \"local\" { path = \"../.terraform-state/stage1.tfstate\" }" - - "Production: backend \"azurerm\" { resource_group_name = \"terraform-state-rg\"; storage_account_name = \"tfstate12345\"; container_name = \"tfstate\"; key = \"stage1.tfstate\" }" - - - id: TF-008 - name: Complete Stage Outputs - description: >- - Every stage's outputs.tf MUST export all resource names, IDs, and - endpoints that ANY downstream stage or application needs. At minimum: - resource group name(s), managed identity client_id/principal_id, - service endpoints, workspace IDs. NEVER output sensitive values - (keys, connection strings) — if local auth is disabled, omit keys entirely. - applies_to: - - terraform-agent - examples: - - "output \"resource_group_name\" { value = azurerm_resource_group.main.name }" - - "output \"managed_identity_client_id\" { value = azurerm_user_assigned_identity.app.client_id }" - - "# Do NOT output primary_key when local auth is disabled" - - - id: TF-009 - name: Complete and Robust deploy.sh - description: >- - Every stage MUST include a deploy.sh that is syntactically complete - and runnable. It must use set -euo pipefail, include Azure login - verification, run terraform init/plan/apply, export outputs to JSON, - and include error handling via trap. NEVER truncate the script or - leave strings unclosed. - applies_to: - - terraform-agent - examples: - - "#!/bin/bash\\nset -euo pipefail\\ntrap 'echo Deploy failed' ERR" - - "terraform output -json > stage-1-outputs.json" - - - id: TF-010 - name: Companion Resources for Disabled Auth - description: >- - When disabling local/key-based authentication on any service - (local_authentication_disabled = true, shared_access_key_enabled = false), - the SAME stage MUST also create: (1) a user-assigned managed identity, - (2) RBAC role assignments granting that identity access, (3) outputs - for the identity's client_id and principal_id. Without these companion - resources, applications cannot authenticate and the deployment is broken. - applies_to: - - terraform-agent - - cloud-architect - examples: - - "resource \"azurerm_user_assigned_identity\" \"app\" { ... }" - - "resource \"azurerm_cosmosdb_sql_role_assignment\" \"app\" { principal_id = azurerm_user_assigned_identity.app.principal_id }" diff --git a/azext_prototype/governance/standards/validate.py b/azext_prototype/governance/standards/validate.py index 248d9e5..158b79a 100644 --- a/azext_prototype/governance/standards/validate.py +++ b/azext_prototype/governance/standards/validate.py @@ -1,309 +1,138 @@ -#!/usr/bin/env python -"""Validate standards YAML files against the expected schema. - -Usage: - # Validate all built-in standards files - python -m azext_prototype.governance.standards.validate - - # Validate specific files - python -m azext_prototype.governance.standards.validate path/to/file.yaml ... - - # Validate a directory recursively - python -m azext_prototype.governance.standards.validate --dir azext_prototype/governance/standards/ - - # Strict mode — warnings are treated as errors - python -m azext_prototype.governance.standards.validate --strict - - # As a pre-commit hook (validates staged standards YAML files) - python -m azext_prototype.governance.standards.validate --hook - -Exit codes: - 0 — all files valid - 1 — validation errors found -""" - -from __future__ import annotations - -import argparse -import subprocess -import sys -from dataclasses import dataclass -from pathlib import Path - -import yaml - -# ------------------------------------------------------------------ # -# Validation error -# ------------------------------------------------------------------ # - - -@dataclass -class ValidationError: - """A single validation issue found in a standards file.""" - - file: str - message: str - severity: str = "error" # error | warning - - def __str__(self) -> str: - return f"[{self.severity.upper()}] {self.file}: {self.message}" - - -# ------------------------------------------------------------------ # -# Schema validation -# ------------------------------------------------------------------ # - -_STANDARDS_DIR = Path(__file__).resolve().parent - -# Valid categories — keep in sync with the standards directory layout -VALID_CATEGORIES = ("principles", "terraform", "bicep", "application") - - -def validate_standards_file(path: Path) -> list[ValidationError]: - """Validate a single standards YAML file against the schema. - - Returns a list of validation errors (empty means valid). - """ - errors: list[ValidationError] = [] - filename = str(path) - - # ---- Parse YAML ---- - try: - data = yaml.safe_load(path.read_text(encoding="utf-8")) or {} - except yaml.YAMLError as exc: - errors.append(ValidationError(filename, f"Invalid YAML: {exc}")) - return errors - except OSError as exc: - errors.append(ValidationError(filename, f"Cannot read file: {exc}")) - return errors - - if not isinstance(data, dict): - errors.append(ValidationError(filename, "Root element must be a mapping")) - return errors - - # ---- domain (required) ---- - if "domain" not in data: - errors.append(ValidationError(filename, "Missing required key: 'domain'")) - elif not isinstance(data["domain"], str): - errors.append(ValidationError(filename, "'domain' must be a string")) - - # ---- category (required) ---- - category = data.get("category") - if category is None: - errors.append(ValidationError(filename, "Missing required key: 'category'")) - elif not isinstance(category, str): - errors.append(ValidationError(filename, "'category' must be a string")) - elif category not in VALID_CATEGORIES: - errors.append( - ValidationError( - filename, - f"category '{category}' is not valid. Allowed: {', '.join(VALID_CATEGORIES)}", - severity="warning", - ) - ) - - # ---- description (recommended) ---- - if "description" not in data: - errors.append( - ValidationError(filename, "Missing 'description' — recommended for documentation", severity="warning") - ) - - # ---- principles (required) ---- - principles = data.get("principles") - if principles is None: - errors.append(ValidationError(filename, "Missing required key: 'principles'")) - return errors - - if not isinstance(principles, list): - errors.append(ValidationError(filename, "'principles' must be a list")) - return errors - - if len(principles) == 0: - errors.append(ValidationError(filename, "'principles' is empty — file has no standards", severity="warning")) - - principle_ids: set[str] = set() - for i, entry in enumerate(principles): - prefix = f"principles[{i}]" - if not isinstance(entry, dict): - errors.append(ValidationError(filename, f"{prefix}: must be a mapping")) - continue - - # id — required, unique within file - pid = entry.get("id") - if pid is None: - errors.append(ValidationError(filename, f"{prefix} missing required key: 'id'")) - elif not isinstance(pid, str): - errors.append(ValidationError(filename, f"{prefix}.id must be a string")) - else: - if pid in principle_ids: - errors.append(ValidationError(filename, f"{prefix}: duplicate principle id '{pid}'")) - principle_ids.add(pid) - - # name — required - name = entry.get("name") - if name is None: - errors.append(ValidationError(filename, f"{prefix} missing required key: 'name'")) - elif not isinstance(name, str): - errors.append(ValidationError(filename, f"{prefix}.name must be a string")) - - # description — required - desc = entry.get("description") - if desc is None: - errors.append(ValidationError(filename, f"{prefix} missing required key: 'description'")) - elif not isinstance(desc, str): - errors.append(ValidationError(filename, f"{prefix}.description must be a string")) - - # applies_to — optional, must be list of strings - applies_to = entry.get("applies_to") - if applies_to is not None: - if not isinstance(applies_to, list): - errors.append(ValidationError(filename, f"{prefix}.applies_to must be a list")) - elif len(applies_to) == 0: - errors.append( - ValidationError( - filename, - f"{prefix}.applies_to is empty — standard will apply to no agents", - severity="warning", - ) - ) - else: - for j, agent in enumerate(applies_to): - if not isinstance(agent, str): - errors.append(ValidationError(filename, f"{prefix}.applies_to[{j}] must be a string")) - - # examples — optional, must be list of strings - examples = entry.get("examples") - if examples is not None: - if not isinstance(examples, list): - errors.append(ValidationError(filename, f"{prefix}.examples must be a list")) - else: - for j, ex in enumerate(examples): - if not isinstance(ex, str): - errors.append(ValidationError(filename, f"{prefix}.examples[{j}] must be a string")) - - return errors - - -def validate_standards_directory(directory: Path) -> list[ValidationError]: - """Validate all YAML files under a directory recursively. - - Returns a combined list of validation errors across all files. - """ - all_errors: list[ValidationError] = [] - if not directory.is_dir(): - return all_errors - - for yaml_file in sorted(directory.rglob("*.yaml")): - all_errors.extend(validate_standards_file(yaml_file)) - - return all_errors - - -# ------------------------------------------------------------------ # -# CLI -# ------------------------------------------------------------------ # - - -def _get_staged_standards_files() -> list[Path]: - """Return staged standards YAML files from the git index.""" - try: - result = subprocess.run( - ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"], - capture_output=True, - text=True, - check=True, - ) - except (subprocess.CalledProcessError, FileNotFoundError): - return [] - - return [ - Path(f) - for f in result.stdout.strip().splitlines() - if f.endswith(".yaml") and "standards" in f and "validate" not in f - ] - - -def main(argv: list[str] | None = None) -> int: - """Entry point for the standards validator.""" - parser = argparse.ArgumentParser(description="Validate standards YAML files against the expected schema.") - parser.add_argument( - "files", - nargs="*", - help="Specific YAML files to validate.", - ) - parser.add_argument( - "--dir", - type=str, - default=None, - help="Validate all YAML files under this directory recursively.", - ) - parser.add_argument( - "--strict", - action="store_true", - help="Treat warnings as errors.", - ) - parser.add_argument( - "--hook", - action="store_true", - help="Pre-commit hook mode: validate staged standards YAML files.", - ) - - args = parser.parse_args(argv) - - errors: list[ValidationError] = [] - - if args.hook: - staged = _get_staged_standards_files() - if not staged: - return 0 - sys.stdout.write(f"Validating {len(staged)} staged standards file(s)...\n") - for path in staged: - errors.extend(validate_standards_file(path)) - - elif args.dir: - directory = Path(args.dir) - if not directory.is_dir(): - sys.stderr.write(f"Error: '{args.dir}' is not a directory\n") - return 1 - yaml_files = sorted(directory.rglob("*.yaml")) - sys.stdout.write(f"Validating {len(yaml_files)} standards file(s) in {args.dir}...\n") - errors.extend(validate_standards_directory(directory)) - - elif args.files: - sys.stdout.write(f"Validating {len(args.files)} standards file(s)...\n") - for filepath in args.files: - path = Path(filepath) - if not path.exists(): - sys.stderr.write(f"Error: '{filepath}' does not exist\n") - return 1 - errors.extend(validate_standards_file(path)) - - else: - # Default: validate built-in standards - yaml_files = sorted(_STANDARDS_DIR.rglob("*.yaml")) - sys.stdout.write(f"Validating {len(yaml_files)} built-in standards file(s)...\n") - errors.extend(validate_standards_directory(_STANDARDS_DIR)) - - # Report results - if not errors: - sys.stdout.write("All standards files are valid.\n") - return 0 - - actual_errors = [e for e in errors if e.severity == "error"] - warnings = [e for e in errors if e.severity == "warning"] - - for err in errors: - sys.stdout.write(f"{err}\n") - - sys.stdout.write(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)\n") - - if actual_errors: - return 1 - if args.strict and warnings: - return 1 - - return 0 - - -if __name__ == "__main__": - sys.exit(main()) +#!/usr/bin/env python +"""Validate standards YAML files against the unified schema. + +Usage: + python -m azext_prototype.governance.standards.validate + python -m azext_prototype.governance.standards.validate --strict + python -m azext_prototype.governance.standards.validate --dir path/to/dir + +Exit codes: + 0 — all files valid + 1 — validation errors found +""" + +from __future__ import annotations + +import argparse +import sys +from dataclasses import dataclass +from pathlib import Path + +import yaml + +_STANDARDS_DIR = Path(__file__).resolve().parent + +_REQUIRED_TOP_KEYS = {"kind", "domain", "description", "last_updated", "principles"} + + +@dataclass +class ValidationError: + """A single validation issue found in a standards file.""" + + file: str + message: str + severity: str = "error" + + def __str__(self) -> str: + return f"[{self.severity.upper()}] {self.file}: {self.message}" + + +def validate_standards_file(path: Path) -> list[ValidationError]: + """Validate a single standards YAML file.""" + errors: list[ValidationError] = [] + filename = str(path) + + try: + data = yaml.safe_load(path.read_text(encoding="utf-8")) or {} + except yaml.YAMLError as exc: + errors.append(ValidationError(filename, f"Invalid YAML: {exc}")) + return errors + except OSError as exc: + errors.append(ValidationError(filename, f"Cannot read file: {exc}")) + return errors + + if not isinstance(data, dict): + errors.append(ValidationError(filename, "Root element must be a mapping")) + return errors + + for key in _REQUIRED_TOP_KEYS: + if key not in data: + errors.append(ValidationError(filename, f"Missing required key: '{key}'")) + + if data.get("kind") != "standard": + errors.append(ValidationError(filename, f"kind must be 'standard', got '{data.get('kind')}'")) + + principles = data.get("principles", []) + if not isinstance(principles, list): + errors.append(ValidationError(filename, "'principles' must be a list")) + return errors + + principle_ids: set[str] = set() + for i, entry in enumerate(principles): + prefix = f"principles[{i}]" + if not isinstance(entry, dict): + errors.append(ValidationError(filename, f"{prefix}: must be a mapping")) + continue + + pid = entry.get("id", "") + if not pid: + errors.append(ValidationError(filename, f"{prefix}: missing 'id'")) + elif pid in principle_ids: + errors.append(ValidationError(filename, f"{prefix}: duplicate id '{pid}'")) + else: + principle_ids.add(pid) + + if not entry.get("description"): + errors.append(ValidationError(filename, f"{prefix} ({pid}): missing 'description'")) + + applies_to = entry.get("applies_to") + if applies_to is not None and not isinstance(applies_to, list): + errors.append(ValidationError(filename, f"{prefix} ({pid}): 'applies_to' must be a list")) + + return errors + + +def validate_standards_directory(directory: Path) -> list[ValidationError]: + """Validate all standards YAML files under a directory recursively.""" + all_errors: list[ValidationError] = [] + if not directory.is_dir(): + return all_errors + for f in sorted(directory.rglob("*.yaml")): + all_errors.extend(validate_standards_file(f)) + return all_errors + + +def main(argv: list[str] | None = None) -> int: + """CLI entry point.""" + parser = argparse.ArgumentParser(description="Validate standards YAML files.") + parser.add_argument("files", nargs="*", help="Specific files to validate") + parser.add_argument("--dir", type=str, help="Directory to validate recursively") + parser.add_argument("--strict", action="store_true", help="Treat warnings as errors") + args = parser.parse_args(argv) + + if args.dir: + errors = validate_standards_directory(Path(args.dir)) + elif args.files: + errors = [] + for f in args.files: + errors.extend(validate_standards_file(Path(f))) + else: + errors = validate_standards_directory(_STANDARDS_DIR) + + if not errors: + print("All standards files valid.") + return 0 + + for e in errors: + print(e) + + actual = [e for e in errors if e.severity == "error"] + warnings = [e for e in errors if e.severity == "warning"] + + if actual or (args.strict and warnings): + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/azext_prototype/governance/transforms/__init__.py b/azext_prototype/governance/transforms/__init__.py new file mode 100644 index 0000000..f5ff700 --- /dev/null +++ b/azext_prototype/governance/transforms/__init__.py @@ -0,0 +1,463 @@ +"""Post-generation transforms — deterministic fixes for known AI fabrications. + +Transforms run after file generation and before QA review. They detect +and automatically fix known fabrication patterns (e.g., ARM property +placement errors) without AI calls or token cost. + +Directory layout:: + + transforms/ + ├── __init__.py # This module + ├── monitoring/ + │ └── log-analytics.transform.yaml + ├── data/ + │ └── cosmos-db.transform.yaml + └── (future: networking/, compute/, etc.) + +Usage:: + + from azext_prototype.governance.transforms import apply + + content, applied_ids = apply( + content=generated_code, + services=["Microsoft.OperationalInsights/workspaces"], + iac_tool="terraform", + ) +""" + +from __future__ import annotations + +import logging +import re +from dataclasses import dataclass, field +from pathlib import Path +from typing import Callable + +from azext_prototype.governance import safe_load_yaml + +logger = logging.getLogger(__name__) + +_TRANSFORMS_DIR = Path(__file__).parent +_cache: list["Transform"] | None = None + + +@dataclass +class Transform: + """A single deterministic transform rule.""" + + id: str + domain: str + description: str = "" + rationale: str = "" + applies_to: list[str] = field(default_factory=list) + targets: list = field(default_factory=list) + search: str = "" + replace: str = "" + transform_type: str = "regex" # "regex" or "structured" + handler: str = "" # Python function name for structured transforms + + +def load(directory: Path | None = None) -> list[Transform]: + """Load all transform YAML files (cached). + + Falls back to the built-in ``transforms/`` directory shipped + with the extension. + """ + global _cache # noqa: PLW0603 + if _cache is not None: + return _cache + + target = directory or _TRANSFORMS_DIR + transforms: list[Transform] = [] + + if not target.is_dir(): + logger.warning("Transforms directory not found: %s", target) + _cache = [] + return _cache + + for yaml_file in sorted(target.rglob("*.transform.yaml")): + data = safe_load_yaml(yaml_file) + if not isinstance(data, dict): + continue + + domain = data.get("domain", yaml_file.stem.replace(".transform", "")) + transform_list = data.get("transforms", []) + + for idx, entry in enumerate(transform_list, 1): + if not isinstance(entry, dict): + continue + + transform_id = entry.get("id", f"TFM-{domain.upper()}-{idx:03d}") + search = entry.get("search", "") + replace_val = entry.get("replace", "") + + if not search: + continue + + check_applies_to = entry.get("applies_to", []) + if not isinstance(check_applies_to, list): + check_applies_to = [] + + targets_raw = entry.get("targets", []) + if isinstance(targets_raw, dict): + targets_raw = [targets_raw] + if not isinstance(targets_raw, list): + targets_raw = [] + + transforms.append( + Transform( + id=transform_id, + domain=domain, + description=str(entry.get("description", "")), + rationale=str(entry.get("rationale", "")), + applies_to=check_applies_to, + targets=targets_raw, + search=search, + replace=replace_val, + transform_type=str(entry.get("type", "regex")), + handler=str(entry.get("handler", "")), + ) + ) + + _cache = transforms + return _cache + + +def apply( + content: str, + services: list[str] | None = None, + iac_tool: str | None = None, + agent_name: str | None = None, + stage: dict | None = None, + stage_content: str | None = None, +) -> tuple[str, list[str]]: + """Apply transforms to generated content. + + Parameters + ---------- + content: + The generated IaC code to transform. + services: + ARM resource type namespaces for this stage. + iac_tool: + ``"terraform"`` or ``"bicep"``. + agent_name: + Agent that generated the content. + stage: + Stage dict with ``stage`` (number), ``name``, ``dir``, etc. + Used by structured handlers that need stage context. + + Returns + ------- + tuple[str, list[str]]: + ``(transformed_content, list_of_applied_transform_ids)``. + If no transforms matched, content is returned unchanged. + """ + transforms = load() + if not transforms: + return content, [] + + _TOOL_TO_AGENT = {"terraform": "terraform-agent", "bicep": "bicep-agent"} + effective_agent = agent_name or _TOOL_TO_AGENT.get(iac_tool or "", "") + + svc_set = {s.lower() for s in services} if services else None + + applied: list[str] = [] + result = content + + for tfm in transforms: + # Filter by agent + if tfm.applies_to and effective_agent and effective_agent not in tfm.applies_to: + continue + + # Filter by service namespace + if svc_set is not None: + tfm_services: set[str] = set() + for t in tfm.targets: + if isinstance(t, dict): + tfm_services.update(s.lower() for s in t.get("services", [])) + if tfm_services and not (tfm_services & svc_set): + continue + + # Apply the transform + if tfm.transform_type == "regex": + try: + new_result, count = re.subn(tfm.search, tfm.replace, result, flags=re.MULTILINE | re.DOTALL) + if count > 0: + result = new_result + applied.append(tfm.id) + logger.debug("Transform %s applied (%d replacements)", tfm.id, count) + except re.error as e: + logger.warning("Transform %s has invalid regex: %s", tfm.id, e) + elif tfm.transform_type == "structured" and tfm.handler: + handler_fn = _STRUCTURED_HANDLERS.get(tfm.handler) + if handler_fn: + import inspect + + params = inspect.signature(handler_fn).parameters + kwargs: dict = {} + if "stage" in params: + kwargs["stage"] = stage + if "stage_content" in params: + kwargs["stage_content"] = stage_content + new_result = handler_fn(result, **kwargs) if kwargs else handler_fn(result) + if new_result != result: + result = new_result + applied.append(tfm.id) + logger.debug("Transform %s applied (structured handler: %s)", tfm.id, tfm.handler) + else: + logger.warning("Transform %s references unknown handler: %s", tfm.id, tfm.handler) + + return result, applied + + +# ------------------------------------------------------------------ +# Structured transform handlers +# ------------------------------------------------------------------ + + +def _remove_unused_remote_state(content: str, stage_content: str | None = None) -> str: + """Remove terraform_remote_state blocks that are never referenced. + + Scans for ``data "terraform_remote_state" "name"`` blocks and checks + if ``data.terraform_remote_state.name`` appears anywhere in the full + stage content (all files). Removes unreferenced blocks and their + state path variables. + + Parameters + ---------- + stage_content: + Concatenated content of ALL files in the stage. Used for + cross-file reference checking (e.g., remote state declared in + main.tf but referenced in locals.tf). + """ + # Find all remote state block names + rs_pattern = re.compile( + r'data\s+"terraform_remote_state"\s+"(\w+)"\s*\{[^}]*\}', + re.DOTALL, + ) + matches = list(rs_pattern.finditer(content)) + if not matches: + return content + + # Use full stage content for reference checking if available + reference_text = stage_content or content + + result = content + for match in reversed(matches): # reverse to preserve offsets + name = match.group(1) + ref = f"data.terraform_remote_state.{name}" + + # Count references in full stage content, excluding the declaration block + ref_count = reference_text.count(ref) + block_self_refs = match.group(0).count(ref) + external_refs = ref_count - block_self_refs + + if external_refs <= 0: + # Remove the block from this file's content + result = result[: match.start()] + result[match.end() :] + logger.debug("Removed unused terraform_remote_state.%s", name) + + # Remove corresponding state path variable + var_pattern = re.compile( + rf'variable\s+"{name}_state_path"\s*\{{[^}}]*\}}\s*\n?', + re.DOTALL, + ) + result = var_pattern.sub("", result) + + return result + + +def _remove_private_endpoint_resources(content: str) -> str: + """Remove private endpoint and DNS zone resources from non-networking stages. + + Matches ``azapi_resource`` blocks whose type contains: + - ``Microsoft.Network/privateEndpoints`` + - ``Microsoft.Network/privateDnsZones`` + - ``privateDnsZoneGroups`` + - ``virtualNetworkLinks`` under privateDnsZones + + Also removes associated locals, variables, and outputs that reference + the removed resources. + """ + pe_types = ( + "microsoft.network/privateendpoints", + "microsoft.network/privatednszones", + "privatednszonegroups", + "virtualnetworklinks", + ) + + # Find resource block starts and use brace counting to find the end + block_start_pattern = re.compile( + r'resource\s+"azapi_resource"\s+"(\w+)"\s*\{', + ) + + removed_names: list[str] = [] + result = content + + for match in reversed(list(block_start_pattern.finditer(result))): + resource_name = match.group(1) + # Find the matching closing brace using brace counting + start = match.start() + brace_start = match.end() - 1 # position of opening { + depth = 1 + pos = brace_start + 1 + while pos < len(result) and depth > 0: + if result[pos] == "{": + depth += 1 + elif result[pos] == "}": + depth -= 1 + pos += 1 + if depth != 0: + continue # malformed block, skip + + block_text = result[start:pos] + # Check if this block's type is a PE/DNS type + type_match = re.search(r'type\s*=\s*"([^"]+)"', block_text) + if not type_match: + continue + resource_type = type_match.group(1).lower() + if any(pt in resource_type for pt in pe_types): + # Remove the block plus any trailing whitespace/newlines + end = pos + while end < len(result) and result[end] in ("\n", "\r", " "): + end += 1 + result = result[:start] + result[end:] + removed_names.append(resource_name) + logger.debug("Removed PE/DNS resource: azapi_resource.%s", resource_name) + + if not removed_names: + return content + + # Remove outputs referencing removed resources + for name in removed_names: + output_pattern = re.compile( + rf'output\s+"\w*{re.escape(name)}\w*"\s*\{{[^}}]*\}}\s*\n?', + re.DOTALL, + ) + result = output_pattern.sub("", result) + + # Remove variables for PE/DNS (common patterns) + for var_name in ("private_endpoint_subnet_id", "private_dns_zone_id", "enable_private_endpoint"): + var_pattern = re.compile( + rf'variable\s+"{var_name}"\s*\{{[^}}]*\}}\s*\n?', + re.DOTALL, + ) + result = var_pattern.sub("", result) + + return result + + +def _add_response_export_values(content: str) -> str: + """Add ``response_export_values = ["*"]`` to azapi_resource blocks missing it. + + Finds each ``resource "azapi_resource" "name" { ... }`` block and checks + if ``response_export_values`` appears inside it. If missing, inserts it + after the ``parent_id`` line (or after ``type`` if no ``parent_id``). + """ + # Match azapi_resource blocks + block_pattern = re.compile( + r'(resource\s+"azapi_resource"\s+"\w+"\s*\{)(.*?\n)((?:.*?\n)*?)(})', + re.DOTALL, + ) + + def _inject(match: re.Match) -> str: # type: ignore[type-arg] + full = match.group(0) + if "response_export_values" in full: + return full # already has it + + header = match.group(1) + first_line = match.group(2) + body = match.group(3) + closing = match.group(4) + + # Find insertion point: after parent_id, or after location, or after type + lines = (first_line + body).splitlines(keepends=True) + insert_idx = len(lines) # fallback: before closing brace + for i, line in enumerate(lines): + stripped = line.strip() + if stripped.startswith("parent_id"): + insert_idx = i + 1 + break + if stripped.startswith("location"): + insert_idx = i + 1 + elif stripped.startswith("type") and insert_idx == len(lines): + insert_idx = i + 1 + + # Detect indentation from the type/parent_id line + indent = " " + if insert_idx > 0 and insert_idx <= len(lines): + prev_line = lines[insert_idx - 1] + leading = len(prev_line) - len(prev_line.lstrip()) + indent = " " * leading + + lines.insert(insert_idx, f'\n{indent}response_export_values = ["*"]\n') + return header + "".join(lines) + closing + + new_content = block_pattern.sub(_inject, content) + if new_content != content: + logger.debug("Added response_export_values to azapi_resource blocks") + return new_content + + +def _add_resource_group_parent_id(content: str) -> str: + """Add ``parent_id`` to resource group azapi_resource blocks missing it. + + Finds ``azapi_resource`` blocks whose type contains + ``Microsoft.Resources/resourceGroups`` and injects + ``parent_id = "/subscriptions/${var.subscription_id}"`` + after the ``name`` line. + """ + # Match azapi_resource blocks with resourceGroups type + block_pattern = re.compile( + r'(resource\s+"azapi_resource"\s+"\w+"\s*\{)(.*?)(})', + re.DOTALL, + ) + + def _inject(match: re.Match) -> str: # type: ignore[type-arg] + full = match.group(0) + if "resourcegroups" not in full.lower(): + return full + if "parent_id" in full: + return full # already has it + + header = match.group(1) + body = match.group(2) + closing = match.group(3) + + # Insert after the name line + lines = body.splitlines(keepends=True) + insert_idx = len(lines) + for i, line in enumerate(lines): + if line.strip().startswith("name"): + insert_idx = i + 1 + break + + # Detect indentation + indent = " " + if insert_idx > 0 and insert_idx <= len(lines): + prev_line = lines[insert_idx - 1] + leading = len(prev_line) - len(prev_line.lstrip()) + indent = " " * leading + + lines.insert(insert_idx, f'{indent}parent_id = "/subscriptions/${{var.subscription_id}}"\n') + return header + "".join(lines) + closing + + new_content = block_pattern.sub(_inject, content) + if new_content != content: + logger.debug("Added parent_id to resource group azapi_resource") + return new_content + + +_STRUCTURED_HANDLERS: dict[str, Callable] = { + "remove_unused_remote_state": _remove_unused_remote_state, + "remove_private_endpoint_resources": _remove_private_endpoint_resources, + "add_response_export_values": _add_response_export_values, + "add_resource_group_parent_id": _add_resource_group_parent_id, +} + + +def reset_cache() -> None: + """Clear the module-level cache (useful in tests).""" + global _cache # noqa: PLW0603 + _cache = None diff --git a/azext_prototype/governance/transforms/data/cosmos-db.transform.yaml b/azext_prototype/governance/transforms/data/cosmos-db.transform.yaml new file mode 100644 index 0000000..fdab1b4 --- /dev/null +++ b/azext_prototype/governance/transforms/data/cosmos-db.transform.yaml @@ -0,0 +1,40 @@ +kind: transform +domain: data +description: Automatic corrections for Cosmos DB ARM schema fabrications +last_updated: '2026-04-06' +transforms: +- id: TFM-CDB-001 + description: Replace capacityMode with EnableServerless capability + rationale: The Cosmos DB ARM schema does not have a capacityMode property. + Setting it is silently ignored and serverless mode is not activated. + The correct pattern uses capabilities with EnableServerless. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + type: regex + search: 'capacityMode\s*=\s*"[Ss]erverless"' + replace: 'capabilities = [{ name = "EnableServerless" }]' +- id: TFM-CDB-002 + description: Inject backupPolicy for serverless Cosmos DB accounts + rationale: Serverless Cosmos DB accounts require backupPolicy.type = Continuous. + ARM rejects Periodic for serverless, and omitting backupPolicy entirely + causes undefined behavior on some API versions. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.DocumentDB/databaseAccounts + type: regex + search: '(capabilities\s*=\s*\[\s*\{\s*name\s*=\s*"EnableServerless"\s*\}\s*\])(?!\s*\n\s*backupPolicy)' + replace: | + \1 + backupPolicy = { + type = "Continuous" + continuousModeProperties = { + tier = "Continuous7Days" + } + } diff --git a/azext_prototype/governance/transforms/iac/terraform-export-values.transform.yaml b/azext_prototype/governance/transforms/iac/terraform-export-values.transform.yaml new file mode 100644 index 0000000..784a16f --- /dev/null +++ b/azext_prototype/governance/transforms/iac/terraform-export-values.transform.yaml @@ -0,0 +1,18 @@ +kind: transform +domain: iac +description: Ensure all azapi_resource blocks have response_export_values +last_updated: '2026-04-06' +transforms: +- id: TFM-TF-002 + description: Add response_export_values = ["*"] to azapi_resource blocks that are missing it + rationale: The azapi provider requires response_export_values to return any output data. + Without it, .output is empty and all downstream references fail silently. This is + the most common generation fabrication — the AI omits it on 25-30% of resources. + applies_to: + - terraform-agent + targets: + - services: [] + type: structured + handler: add_response_export_values + search: azapi_resource without response_export_values + replace: added response_export_values = ["*"] diff --git a/azext_prototype/governance/transforms/iac/terraform-remote-state.transform.yaml b/azext_prototype/governance/transforms/iac/terraform-remote-state.transform.yaml new file mode 100644 index 0000000..df579d0 --- /dev/null +++ b/azext_prototype/governance/transforms/iac/terraform-remote-state.transform.yaml @@ -0,0 +1,19 @@ +kind: transform +domain: iac +description: Remove unused terraform_remote_state blocks and their associated variables +last_updated: '2026-04-06' +transforms: +- id: TFM-TF-001 + description: Remove terraform_remote_state data sources that are declared but never + referenced elsewhere in the generated code + rationale: Unused remote state blocks add unnecessary upstream dependencies, clutter + deploy.sh preflight checks, and confuse QA review. If a data source name does + not appear outside its own block, it serves no purpose. + applies_to: + - terraform-agent + targets: + - services: [] + type: structured + handler: remove_unused_remote_state + search: unused terraform_remote_state + replace: removed diff --git a/azext_prototype/governance/transforms/iac/terraform-resource-group.transform.yaml b/azext_prototype/governance/transforms/iac/terraform-resource-group.transform.yaml new file mode 100644 index 0000000..95a732c --- /dev/null +++ b/azext_prototype/governance/transforms/iac/terraform-resource-group.transform.yaml @@ -0,0 +1,18 @@ +kind: transform +domain: iac +description: Ensure resource group azapi_resource blocks have parent_id +last_updated: '2026-04-06' +transforms: +- id: TFM-RG-001 + description: Add parent_id to resource group resources that are missing it + rationale: The azapi provider requires parent_id on all resources. For resource groups, + parent_id must be /subscriptions/${var.subscription_id}. Without it, terraform plan + fails immediately. + applies_to: + - terraform-agent + targets: + - services: [] + type: structured + handler: add_resource_group_parent_id + search: azapi_resource for resourceGroups without parent_id + replace: added parent_id diff --git a/azext_prototype/governance/transforms/monitoring/log-analytics.transform.yaml b/azext_prototype/governance/transforms/monitoring/log-analytics.transform.yaml new file mode 100644 index 0000000..aac958e --- /dev/null +++ b/azext_prototype/governance/transforms/monitoring/log-analytics.transform.yaml @@ -0,0 +1,18 @@ +kind: transform +domain: monitoring +description: Automatic corrections for Log Analytics workspace ARM property placement +last_updated: '2026-04-06' +transforms: +- id: TFM-LA-001 + description: Move disableLocalAuth from inside features block to properties root + rationale: ARM silently drops disableLocalAuth if nested inside properties.features. + The property must be a direct child of properties for Log Analytics workspaces. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: + - Microsoft.OperationalInsights/workspaces + type: regex + search: '(features\s*=\s*\{[^}]*?)(\s*disableLocalAuth\s*=\s*\w+\s*\n?)([^}]*\})' + replace: '\1\3' diff --git a/azext_prototype/governance/transforms/networking/private-endpoints.transform.yaml b/azext_prototype/governance/transforms/networking/private-endpoints.transform.yaml new file mode 100644 index 0000000..74ded50 --- /dev/null +++ b/azext_prototype/governance/transforms/networking/private-endpoints.transform.yaml @@ -0,0 +1,21 @@ +kind: transform +domain: networking +description: Remove private endpoint resources from non-networking stages +last_updated: '2026-04-06' +transforms: +- id: TFM-NET-001 + description: Remove private endpoint, private DNS zone, DNS zone link, and DNS zone + group resources from non-networking stages. These resources belong exclusively in + the dedicated Networking stage. + rationale: The architecture mandates a single Networking stage that creates ALL private + endpoints, DNS zones, and DNS zone groups. Service stages must NOT create these + resources — they only set publicNetworkAccess to Disabled on their own resources. + applies_to: + - terraform-agent + - bicep-agent + targets: + - services: [] + type: structured + handler: remove_private_endpoint_resources + search: privateEndpoints or privateDnsZones in non-networking stage + replace: removed diff --git a/azext_prototype/governance/validate.py b/azext_prototype/governance/validate.py new file mode 100644 index 0000000..a22b483 --- /dev/null +++ b/azext_prototype/governance/validate.py @@ -0,0 +1,460 @@ +#!/usr/bin/env python +"""Validate governance YAML files: policies, anti-patterns, standards, and transforms. + +Usage: + # Validate everything + python -m azext_prototype.governance.validate --all --strict + + # Validate individual areas + python -m azext_prototype.governance.validate --policies --strict + python -m azext_prototype.governance.validate --anti-patterns --strict + python -m azext_prototype.governance.validate --standards --strict + + # Combine flags + python -m azext_prototype.governance.validate --policies --anti-patterns --strict + +Exit codes: + 0 -- all files valid + 1 -- validation errors found +""" + +from __future__ import annotations + +import argparse +import sys +from dataclasses import dataclass +from pathlib import Path + +import yaml + +_GOVERNANCE_DIR = Path(__file__).resolve().parent + + +# ------------------------------------------------------------------ # +# Shared validation result +# ------------------------------------------------------------------ # + + +@dataclass +class ValidationError: + """A single validation issue.""" + + file: str + message: str + severity: str = "error" + + def __str__(self) -> str: + return f"[{self.severity.upper()}] {self.file}: {self.message}" + + +# ------------------------------------------------------------------ # +# Policy validation (delegates to existing engine) +# ------------------------------------------------------------------ # + + +def validate_policies() -> list[ValidationError]: + """Validate all policy YAML files.""" + from azext_prototype.governance.policies import ( + validate_policy_directory, + ) + + policy_dir = _GOVERNANCE_DIR / "policies" + if not policy_dir.is_dir(): + return [] + + policy_errors = validate_policy_directory(policy_dir) + + # Convert to our ValidationError type + return [ValidationError(file=e.file, message=e.message, severity=e.severity) for e in policy_errors] + + +# ------------------------------------------------------------------ # +# Anti-pattern validation +# ------------------------------------------------------------------ # + + +def validate_anti_patterns() -> list[ValidationError]: + """Validate all anti-pattern YAML files against the unified schema.""" + ap_dir = _GOVERNANCE_DIR / "anti_patterns" + if not ap_dir.is_dir(): + return [] + + errors: list[ValidationError] = [] + all_ids: dict[str, str] = {} + + required_top = {"kind", "domain", "description", "last_updated", "patterns"} + + for yaml_file in sorted(ap_dir.glob("*.yaml")): + fname = yaml_file.name + try: + data = yaml.safe_load(yaml_file.read_text(encoding="utf-8")) or {} + except (OSError, yaml.YAMLError) as exc: + errors.append(ValidationError(fname, f"Could not load: {exc}")) + continue + + if not isinstance(data, dict): + errors.append(ValidationError(fname, "Root must be a mapping")) + continue + + for key in required_top: + if key not in data: + errors.append(ValidationError(fname, f"Missing required field '{key}'")) + + if data.get("kind") != "anti-pattern": + errors.append(ValidationError(fname, f"kind must be 'anti-pattern', got '{data.get('kind')}'")) + + patterns = data.get("patterns", []) + if not isinstance(patterns, list): + errors.append(ValidationError(fname, "'patterns' must be a list")) + continue + + for idx, entry in enumerate(patterns, 1): + if not isinstance(entry, dict): + errors.append(ValidationError(fname, f"Pattern {idx}: must be a mapping")) + continue + + check_id = entry.get("id") + if not check_id: + errors.append(ValidationError(fname, f"Pattern {idx}: missing 'id'")) + + if not entry.get("description"): + errors.append(ValidationError(fname, f"Pattern {idx} ({check_id}): missing 'description'")) + + if not entry.get("warning_message"): + errors.append(ValidationError(fname, f"Pattern {idx} ({check_id}): missing 'warning_message'")) + + # targets: list of target blocks, each with services and search_patterns + targets = entry.get("targets") + if isinstance(targets, dict): + # Single target block — normalize to list + targets = [targets] + if not isinstance(targets, list) or not targets: + errors.append(ValidationError(fname, f"Pattern {idx} ({check_id}): missing or invalid 'targets'")) + else: + # At least one target block must have search_patterns + has_search = any(isinstance(t, dict) and t.get("search_patterns") for t in targets) + if not has_search: + errors.append( + ValidationError(fname, f"Pattern {idx} ({check_id}): no target block has 'search_patterns'") + ) + + if check_id and check_id in all_ids: + errors.append(ValidationError(fname, f"Duplicate id '{check_id}' (also in {all_ids[check_id]})")) + elif check_id: + all_ids[check_id] = fname + + return errors + + +# ------------------------------------------------------------------ # +# Standards validation +# ------------------------------------------------------------------ # + + +def validate_standards() -> list[ValidationError]: + """Validate all standards YAML files against the unified schema.""" + std_dir = _GOVERNANCE_DIR / "standards" + if not std_dir.is_dir(): + return [] + + errors: list[ValidationError] = [] + all_ids: dict[str, str] = {} + + required_top = {"kind", "domain", "description", "last_updated", "principles"} + + for yaml_file in sorted(std_dir.rglob("*.yaml")): + fname = str(yaml_file.relative_to(std_dir)) + try: + data = yaml.safe_load(yaml_file.read_text(encoding="utf-8")) or {} + except (OSError, yaml.YAMLError) as exc: + errors.append(ValidationError(fname, f"Could not load: {exc}")) + continue + + if not isinstance(data, dict): + errors.append(ValidationError(fname, "Root must be a mapping")) + continue + + for key in required_top: + if key not in data: + errors.append(ValidationError(fname, f"Missing required field '{key}'")) + + if data.get("kind") != "standard": + errors.append(ValidationError(fname, f"kind must be 'standard', got '{data.get('kind')}'")) + + principles = data.get("principles", []) + if not isinstance(principles, list): + errors.append(ValidationError(fname, "'principles' must be a list")) + continue + + for idx, entry in enumerate(principles, 1): + if not isinstance(entry, dict): + errors.append(ValidationError(fname, f"Principle {idx}: must be a mapping")) + continue + + pid = entry.get("id") + if not pid: + errors.append(ValidationError(fname, f"Principle {idx}: missing 'id'")) + + if not entry.get("description"): + errors.append(ValidationError(fname, f"Principle {idx} ({pid}): missing 'description'")) + + if pid and pid in all_ids: + errors.append(ValidationError(fname, f"Duplicate id '{pid}' (also in {all_ids[pid]})")) + elif pid: + all_ids[pid] = fname + + applies_to = entry.get("applies_to") + if applies_to is not None and not isinstance(applies_to, list): + errors.append(ValidationError(fname, f"Principle {idx} ({pid}): 'applies_to' must be a list")) + + return errors + + +# ------------------------------------------------------------------ # +# Transform validation +# ------------------------------------------------------------------ # + + +def validate_transforms() -> list[ValidationError]: + """Validate all transform YAML files against the unified schema.""" + tfm_dir = _GOVERNANCE_DIR / "transforms" + if not tfm_dir.is_dir(): + return [] + + errors: list[ValidationError] = [] + all_ids: dict[str, str] = {} + + required_top = {"kind", "domain", "description", "last_updated", "transforms"} + + for yaml_file in sorted(tfm_dir.rglob("*.transform.yaml")): + fname = str(yaml_file.relative_to(tfm_dir)) + try: + data = yaml.safe_load(yaml_file.read_text(encoding="utf-8")) or {} + except (OSError, yaml.YAMLError) as exc: + errors.append(ValidationError(fname, f"Could not load: {exc}")) + continue + + if not isinstance(data, dict): + errors.append(ValidationError(fname, "Root must be a mapping")) + continue + + for key in required_top: + if key not in data: + errors.append(ValidationError(fname, f"Missing required field '{key}'")) + + if data.get("kind") != "transform": + errors.append(ValidationError(fname, f"kind must be 'transform', got '{data.get('kind')}'")) + + transforms = data.get("transforms", []) + if not isinstance(transforms, list): + errors.append(ValidationError(fname, "'transforms' must be a list")) + continue + + for idx, entry in enumerate(transforms, 1): + if not isinstance(entry, dict): + errors.append(ValidationError(fname, f"Transform {idx}: must be a mapping")) + continue + + tid = entry.get("id") + if not tid: + errors.append(ValidationError(fname, f"Transform {idx}: missing 'id'")) + + if not entry.get("description"): + errors.append(ValidationError(fname, f"Transform {idx} ({tid}): missing 'description'")) + + if not entry.get("search"): + errors.append(ValidationError(fname, f"Transform {idx} ({tid}): missing 'search'")) + + if "replace" not in entry: + errors.append(ValidationError(fname, f"Transform {idx} ({tid}): missing 'replace'")) + + if tid and tid in all_ids: + errors.append(ValidationError(fname, f"Duplicate id '{tid}' (also in {all_ids[tid]})")) + elif tid: + all_ids[tid] = fname + + return errors + + +# ------------------------------------------------------------------ # +# Workload template validation +# ------------------------------------------------------------------ # + + +def validate_workloads() -> list[ValidationError]: + """Validate all workload template YAML files against policies.""" + from azext_prototype.templates.validate import validate_template_directory + + template_dir = Path(__file__).resolve().parent.parent / "templates" / "workloads" + if not template_dir.is_dir(): + return [] + + violations = validate_template_directory(template_dir) + + return [ + ValidationError( + file=v.template, + message=f"{v.rule_id} — {v.message}", + severity=v.severity, + ) + for v in violations + ] + + +# ------------------------------------------------------------------ # +# Taxonomy validation +# ------------------------------------------------------------------ # + + +def validate_taxonomy() -> list[ValidationError]: + """Validate taxonomy.yaml structure and consistency with governance files.""" + knowledge_dir = Path(__file__).resolve().parent.parent / "knowledge" + taxonomy_path = knowledge_dir / "taxonomy.yaml" + + if not taxonomy_path.exists(): + return [ValidationError("taxonomy.yaml", "File not found")] + + errors: list[ValidationError] = [] + + try: + data = yaml.safe_load(taxonomy_path.read_text(encoding="utf-8")) or {} + except (OSError, yaml.YAMLError) as exc: + return [ValidationError("taxonomy.yaml", f"Could not load: {exc}")] + + layers = data.get("layers") + if not isinstance(layers, dict): + return [ValidationError("taxonomy.yaml", "'layers' must be a mapping")] + + # Collect all valid capabilities and components + all_capabilities: dict[str, str] = {} # capability → layer + all_components: dict[str, str] = {} # component → capability + + for layer_key, layer_data in layers.items(): + if not isinstance(layer_data, dict): + errors.append(ValidationError("taxonomy.yaml", f"Layer '{layer_key}' must be a mapping")) + continue + + if "display_name" not in layer_data: + errors.append(ValidationError("taxonomy.yaml", f"Layer '{layer_key}': missing 'display_name'")) + + caps = layer_data.get("capabilities") + if not isinstance(caps, dict): + errors.append(ValidationError("taxonomy.yaml", f"Layer '{layer_key}': 'capabilities' must be a mapping")) + continue + + for cap_key, cap_data in caps.items(): + if cap_key in all_capabilities: + errors.append( + ValidationError( + "taxonomy.yaml", + f"Duplicate capability '{cap_key}' in layers '{all_capabilities[cap_key]}' and '{layer_key}'", + ) + ) + all_capabilities[cap_key] = layer_key + + if not isinstance(cap_data, dict): + errors.append( + ValidationError("taxonomy.yaml", f"Capability '{cap_key}' in '{layer_key}' must be a mapping") + ) + continue + + components = cap_data.get("components") + if not isinstance(components, list): + errors.append(ValidationError("taxonomy.yaml", f"Capability '{cap_key}': 'components' must be a list")) + continue + + for comp in components: + if not isinstance(comp, str): + errors.append( + ValidationError("taxonomy.yaml", f"Capability '{cap_key}': component must be a string") + ) + elif comp in all_components: + errors.append( + ValidationError( + "taxonomy.yaml", + f"Duplicate component '{comp}' in capabilities " + f"'{all_components[comp]}' and '{cap_key}'", + ) + ) + else: + all_components[comp] = cap_key + + if not errors: + # Validate that governance targets reference valid taxonomy services + # (check that targets.services entries map to known ARM namespaces — not taxonomy components) + pass # Service validation deferred to namespace-level checks + + return errors + + +# ------------------------------------------------------------------ # +# CLI entry point +# ------------------------------------------------------------------ # + + +def main(argv: list[str] | None = None) -> int: + """Entry point for the governance validator.""" + parser = argparse.ArgumentParser(description="Validate governance YAML files.") + parser.add_argument("--all", action="store_true", help="Validate all governance areas.") + parser.add_argument("--policies", action="store_true", help="Validate policy files.") + parser.add_argument("--anti-patterns", dest="anti_patterns", action="store_true", help="Validate anti-patterns.") + parser.add_argument("--standards", action="store_true", help="Validate standards files.") + parser.add_argument("--workloads", action="store_true", help="Validate workload templates against policies.") + parser.add_argument("--strict", action="store_true", help="Treat warnings as errors.") + + args = parser.parse_args(argv) + + # Default to --all if no specific flags + if not args.all and not args.policies and not args.anti_patterns and not args.standards and not args.workloads: + args.all = True + + errors: list[ValidationError] = [] + areas: list[str] = [] + + if args.all or args.policies: + areas.append("policies") + errors.extend(validate_policies()) + + if args.all or args.anti_patterns: + areas.append("anti-patterns") + errors.extend(validate_anti_patterns()) + + if args.all or args.standards: + areas.append("standards") + errors.extend(validate_standards()) + + if args.all or args.workloads: + areas.append("workloads") + errors.extend(validate_workloads()) + + # Taxonomy and transforms are always validated (part of governance structure) + areas.append("taxonomy") + errors.extend(validate_taxonomy()) + + areas.append("transforms") + errors.extend(validate_transforms()) + + sys.stdout.write(f"Validating: {', '.join(areas)}\n") + + if not errors: + sys.stdout.write("All governance files are valid.\n") + return 0 + + actual_errors = [e for e in errors if e.severity == "error"] + warnings = [e for e in errors if e.severity == "warning"] + + for err in errors: + sys.stdout.write(f"{err}\n") + + sys.stdout.write(f"\n{len(actual_errors)} error(s), {len(warnings)} warning(s)\n") + + if actual_errors: + return 1 + if args.strict and warnings: + return 1 + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/azext_prototype/knowledge/__init__.py b/azext_prototype/knowledge/__init__.py index 9ef8a10..f140fe4 100644 --- a/azext_prototype/knowledge/__init__.py +++ b/azext_prototype/knowledge/__init__.py @@ -13,7 +13,8 @@ ├── services/ # Per-Azure-service knowledge files ├── tools/ # IaC tool patterns (terraform, bicep, deploy-scripts) ├── languages/ # Language-specific patterns (python, csharp, nodejs, auth) - └── roles/ # Agent role templates (architect, infrastructure, developer, analyst) + ├── roles/ # Agent role templates (architect, infrastructure, developer, analyst) + └── layers/ # Layer definitions (core, infrastructure, data, application) Usage:: @@ -70,8 +71,88 @@ def __init__( # ------------------------------------------------------------------ def load_service(self, service_name: str) -> str: - """Load a service knowledge file (e.g. ``cosmos-db``).""" - return self._read_md("services", f"{service_name}.md") + """Load a service knowledge file by name or ARM namespace. + + Resolution order: + 1. ARM namespace match via frontmatter (e.g., ``Microsoft.Sql/servers``) + 2. Friendly name from service registry + 3. Exact filename match + 4. Static mapping table (legacy deployment plan names) + 5. Suffix stripping heuristic + """ + # 1. Try ARM namespace resolution via frontmatter index + namespace_index = self._build_namespace_index() + if service_name in namespace_index: + return self._read_md("services", namespace_index[service_name]) + + # 2. Try friendly_name from service registry + friendly_index = self._build_friendly_index() + if service_name in friendly_index: + return self._read_md("services", friendly_index[service_name]) + + # 3-5. Legacy resolution + resolved = self._resolve_service_file(service_name) + return self._read_md("services", f"{resolved}.md") + + def _build_namespace_index(self) -> dict[str, str]: + """Build a mapping of ARM namespace → filename from frontmatter. + + Cached after first call. + """ + if hasattr(self, "_ns_index"): + return self._ns_index + + index: dict[str, str] = {} + services_dir = self._dir / "services" + if not services_dir.is_dir(): + self._ns_index = index + return index + + for md_file in services_dir.glob("*.md"): + try: + content = md_file.read_text(encoding="utf-8") + if not content.startswith("---\n"): + continue + # Parse frontmatter + end = content.index("---", 4) + frontmatter = content[4:end] + for line in frontmatter.splitlines(): + if line.startswith("service_namespace:"): + ns = line.split(":", 1)[1].strip() + index[ns] = md_file.name + break + except (ValueError, OSError): + continue + + self._ns_index = index + return index + + def _build_friendly_index(self) -> dict[str, str]: + """Build a mapping of friendly_name → filename from service registry. + + Cached after first call. + """ + if hasattr(self, "_fn_index"): + return self._fn_index + + index: dict[str, str] = {} + try: + registry = self.load_service_registry() + if isinstance(registry, dict): + services = registry.get("services", registry) + for ns_key, svc in services.items(): + if isinstance(svc, dict): + fn = svc.get("friendly_name", "") + if fn: + # Find the knowledge file for this namespace + ns_index = self._build_namespace_index() + if ns_key in ns_index: + index[fn] = ns_index[ns_key] + except Exception: + pass + + self._fn_index = index + return index def load_tool(self, tool_name: str) -> str: """Load a tool pattern file (e.g. ``terraform``).""" @@ -85,6 +166,14 @@ def load_role(self, role_name: str) -> str: """Load a role template file (e.g. ``architect``).""" return self._read_md("roles", f"{role_name}.md") + def load_layer(self, layer_name: str) -> str: + """Load a layer definition file (e.g. ``infrastructure``). + + Valid layer names: ``core``, ``infrastructure``, ``data``, + ``application``. + """ + return self._read_md("layers", f"{layer_name}.md") + def load_constraints(self) -> str: """Load the shared constraints document.""" return self._read_md(".", "constraints.md") @@ -119,6 +208,7 @@ def compose_context( tool: str | None = None, language: str | None = None, role: str | None = None, + layer: str | None = None, include_constraints: bool = True, include_service_registry: bool = False, mode: str = "poc", @@ -129,15 +219,19 @@ def compose_context( respecting the token budget. Files are added in priority order: 1. Role template (highest priority — defines the agent's identity) - 2. Constraints (shared rules all agents must follow) - 3. Tool patterns (IaC-specific patterns) - 4. Language patterns (language-specific patterns) - 5. Service knowledge files (per-service, loaded in order given) - 6. Service registry entries (raw reference data, lowest priority) + 2. Layer definition (service boundaries and ownership) + 3. Constraints (shared rules all agents must follow) + 4. Tool patterns (IaC-specific patterns) + 5. Language patterns (language-specific patterns) + 6. Service knowledge files (per-service, loaded in order given) + 7. Service registry entries (raw reference data, lowest priority) If the budget is exceeded, lower-priority content is truncated. Args: + layer: Layer name (``core``, ``infrastructure``, ``data``, + ``application``). When provided, the layer definition + file is included so the agent knows its boundaries. mode: Content filtering mode. ``"poc"`` (default) strips ``## Production Backlog Items`` sections from service files. ``"production"`` or ``"all"`` keep everything. @@ -152,6 +246,11 @@ def compose_context( if content: sections.append((f"ROLE: {role}", content)) + if layer: + content = self.load_layer(layer) + if content: + sections.append((f"LAYER: {layer}", content)) + if include_constraints: content = self.load_constraints() if content: @@ -161,6 +260,11 @@ def compose_context( content = self.load_tool(tool) if content: sections.append((f"TOOL PATTERNS: {tool}", content)) + # Load azapi provider knowledge alongside terraform + if tool == "terraform": + azapi = self.load_tool("azapi-provider") + if azapi: + sections.append(("TOOL PATTERNS: azapi-provider", azapi)) if language: content = self.load_language(language) @@ -240,10 +344,103 @@ def list_roles(self) -> list[str]: """List available role template file names.""" return self._list_dir("roles") + def list_layers(self) -> list[str]: + """List available layer definition file names.""" + return self._list_dir("layers") + # ------------------------------------------------------------------ # Internal helpers # ------------------------------------------------------------------ + # Map deployment plan service names to knowledge file names. + # The plan uses computed names (e.g., "cosmos-account") but knowledge + # files use canonical short names (e.g., "cosmos-db"). + _SERVICE_FILE_MAP: dict[str, str] = { + # Cosmos DB + "cosmos-account": "cosmos-db", + "cosmos-database": "cosmos-db", + "cosmos-container": "cosmos-db", + "cosmos-rbac": "cosmos-db", + # Azure SQL + "sql-server": "azure-sql", + "sql-database": "azure-sql", + "sql-rbac": "azure-sql", + # Container Apps + "container-app-api": "container-apps", + "container-app-worker": "container-apps", + "container-apps-environment": "container-apps", + # Log Analytics / App Insights + "log-analytics-workspace": "log-analytics", + "application-insights": "app-insights", + # Managed Identity + "worker-managed-identity": "managed-identity", + # Storage + "storage-container-attachments": "storage-account", + "storage-rbac": "storage-account", + # Service Bus + "servicebus-namespace": "service-bus", + "servicebus-queue-board-events": "service-bus", + "servicebus-rbac": "service-bus", + # SignalR + "signalr-service": "signalr", + "signalr-connection-string-secret": "signalr", + # Redis + "redis-connection-string-secret": "redis-cache", + # Key Vault + "key-vault-rbac": "key-vault", + # Networking + "subnet-aca": "virtual-network", + "subnet-pe": "virtual-network", + "nsg-aca": "virtual-network", + "nsg-pe": "virtual-network", + "private-dns-zones": "dns-zones", + # RBAC suffixes + "api-keyvault-rbac": "key-vault", + "api-servicebus-rbac": "service-bus", + "api-storage-rbac": "storage-account", + "api-acr-rbac": "container-registry", + "worker-servicebus-rbac": "service-bus", + "worker-cosmos-rbac": "cosmos-db", + "worker-storage-rbac": "storage-account", + "worker-keyvault-rbac": "key-vault", + "worker-acr-rbac": "container-registry", + # Monitoring + "monitor-action-group": "action-groups", + "alert-dlq-depth": "action-groups", + "alert-api-latency": "action-groups", + "alert-async-job-latency": "action-groups", + "alert-error-rate": "action-groups", + } + + def _resolve_service_file(self, service_name: str) -> str: + """Resolve a deployment plan service name to a knowledge file name. + + 1. Exact match (file exists) + 2. Static mapping table + 3. Strip common suffixes (-account, -rbac, -namespace, etc.) + """ + # 1. Exact match + if (self._dir / "services" / f"{service_name}.md").exists(): + return service_name + + # 2. Static mapping + mapped = self._SERVICE_FILE_MAP.get(service_name) + if mapped: + return mapped + + # 3. Strip suffixes and retry + for suffix in ("-account", "-rbac", "-namespace", "-database", "-service", "-workspace"): + stripped = service_name.removesuffix(suffix) + if stripped != service_name and (self._dir / "services" / f"{stripped}.md").exists(): + return stripped + + # 4. Try prefix match (e.g., "cosmos-container-audit-log" → "cosmos-db") + for key, val in self._SERVICE_FILE_MAP.items(): + if service_name.startswith(key.split("-")[0] + "-"): + return val + + return service_name # fallback to original (will 404 gracefully) + def _read_md(self, subdir: str, filename: str) -> str: """Read a markdown file, returning empty string on missing/error.""" if subdir == ".": diff --git a/azext_prototype/knowledge/constraints.md b/azext_prototype/knowledge/constraints.md index ef7bfcc..ee9cb32 100644 --- a/azext_prototype/knowledge/constraints.md +++ b/azext_prototype/knowledge/constraints.md @@ -62,16 +62,16 @@ Use Key Vault references in App Service and Container Apps configuration instead All data and backend services should use private endpoints to eliminate public internet exposure for the data plane. -#### POC Relaxation +Unless told otherwise by the user (via discovery directives or custom policies), all environments — including POC — should disable public network access and use private endpoints. -For POC/prototype environments, private endpoints are **recommended but not mandatory**. Public endpoints are acceptable for rapid prototyping to reduce complexity and setup time. When public endpoints are used: +**CRITICAL — ARCHITECTURE BOUNDARY: A dedicated Networking stage creates ALL private endpoints, private DNS zones, DNS zone links, and DNS zone groups for the entire deployment.** Non-networking stages MUST NOT create these resources. Instead, non-networking stages should: -- Flag private endpoint configuration as a **production backlog item** -- Document which services are publicly exposed -- Ensure service firewalls restrict access to known IP ranges where possible -- Never set firewall rules to `0.0.0.0/0` or `0.0.0.0-255.255.255.255` +- Set `publicNetworkAccess = "Disabled"` on their resources +- Do NOT create `azapi_resource` blocks for private endpoints or DNS zone groups +- Do NOT reference the networking stage via `terraform_remote_state` for PE subnet/DNS IDs +- Do NOT include `private-endpoint.tf` or PE-related variables (`subnet_id`, `private_dns_zone_id`, `enable_private_endpoint`) -For production readiness, all services in the private endpoint reference table below must use private endpoints. +The networking stage discovers which services need private endpoints from the deployment plan and creates all PE + DNS resources in one place. Service-specific knowledge files may show PE patterns for reference, but those patterns belong ONLY in the networking stage. ### 2.2 VNET Integration @@ -81,9 +81,7 @@ When the architecture includes Container Apps, App Service, or Functions: - Use NSGs to restrict traffic between subnets to only required ports - Enable diagnostic logging on NSGs for traffic auditing -#### POC Relaxation - -For POCs, VNET integration is **recommended but not mandatory**. If omitted, document it as a production backlog item. Container Apps Environment without VNET integration is acceptable for prototyping. +Unless told otherwise by the user, all compute services should deploy in a VNET-integrated subnet. ### 2.3 Connectivity Pattern (Production Target) @@ -106,6 +104,35 @@ The following resources legitimately require public IP addresses or public ingre All other services should be internal-only. +### 2.5 ARM Property Placement — `disableLocalAuth` + +Many Azure services support `disableLocalAuth` to enforce Entra-only authentication. This property MUST be placed directly under `properties`, NEVER nested inside `properties.features`: + +```hcl +# CORRECT — disableLocalAuth at properties root +body = { + properties = { + disableLocalAuth = true + features = { + enableLogAccessUsingOnlyResourcePermissions = true + } + } +} +``` + +```hcl +# WRONG — ARM silently drops disableLocalAuth when nested under features +body = { + properties = { + features = { + disableLocalAuth = true # SILENTLY IGNORED — local auth stays enabled + } + } +} +``` + +This applies to: Log Analytics, Service Bus, Event Hubs, Azure OpenAI, Cognitive Services, Container Registry, and any other service with `disableLocalAuth`. + --- ## 3. Security Requirements @@ -215,6 +242,29 @@ All Azure resources must include these tags: - Prefer built-in roles over custom role definitions - Document every role assignment with its justification +### 6.4 CRITICAL: Principal Separation (MANDATORY) + +Administrative roles MUST be assigned to the deploying identity (human or CI/CD +service principal), NOT to the application managed identity: + +| Role Type | Assign To | Examples | +|-----------|-----------|---------| +| Administrative (Key Vault Administrator, Owner, Contributor) | Deploying user/SPN via `var.deployer_object_id` | Break-glass access, secret rotation, infrastructure management | +| Data-plane read/write (Secrets User, Data Contributor, Blob Data Contributor) | Application managed identity (Stage 1) | Runtime access for the application | +| Data-plane read-only (Secrets Reader, Data Reader) | Application managed identity (Stage 1) | Read-only service accounts | + +The deploying user's object ID comes from `var.deployer_object_id` or the current +Azure CLI account context. The application identity's principal ID comes from the +managed identity resource created in Stage 1 (via terraform_remote_state). + +### 6.5 Cosmos DB Data-Plane RBAC (CRITICAL) + +Cosmos DB's built-in data roles (`00000000-0000-0000-0000-000000000001` Data Reader, +`00000000-0000-0000-0000-000000000002` Data Contributor) are **data-plane RBAC** roles. +They MUST be assigned via `Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments`, +NOT via `Microsoft.Authorization/roleAssignments`. Using ARM RBAC (roleAssignments) +for these roles will silently fail — the application will not have data access. + --- ## 7. Private Endpoint Reference @@ -280,9 +330,9 @@ This section clearly delineates what is acceptable in a POC versus what must be | Area | POC Acceptable | Production Required | |------|---------------|-------------------| | **Authentication** | Managed identity (same as production) | Managed identity (no relaxation) | -| **Network isolation** | Public endpoints with service firewalls | Private endpoints for all data services | -| **VNET integration** | Optional; Container Apps external ingress OK | Mandatory; VNET-integrated environments with NSGs | -| **Private DNS zones** | Not required | Required for all private endpoints | +| **Network isolation** | Private endpoints (unless user overrides) | Private endpoints for all data services | +| **VNET integration** | VNET-integrated (unless user overrides) | Mandatory; VNET-integrated environments with NSGs | +| **Private DNS zones** | Required for private endpoints | Required for all private endpoints | | **SKUs** | Free / dev-test / consumption tiers | Production-appropriate SKUs with SLAs | | **Redundancy** | Locally redundant (LRS), single region | Zone-redundant or geo-redundant as needed | | **Backup** | Default backup policies | Custom retention policies, tested restore procedures | @@ -299,7 +349,7 @@ This section clearly delineates what is acceptable in a POC versus what must be ### What POCs Must Still Enforce -Even in a prototype, these constraints are **non-negotiable**: +Even in a prototype, these constraints are **non-negotiable** (unless the user explicitly overrides via discovery directives or custom policies): 1. **Managed identity** for all service-to-service authentication 2. **No hardcoded secrets** in code, config, or environment variables @@ -309,6 +359,8 @@ Even in a prototype, these constraints are **non-negotiable**: 6. **Entra-only auth** for databases (no SQL auth) 7. **Resource tagging** on all resources 8. **Naming conventions** followed consistently +9. **Private endpoints** with publicNetworkAccess disabled on all PaaS services +10. **VNET integration** for all compute services ### Production Backlog Items @@ -324,7 +376,43 @@ When a POC takes an acceptable shortcut, agents must: --- -## 10. Direct Execution Policy +## 10. Taxonomy: Layer → Capability → Component → Resource + +All services and stages follow a four-level hierarchy. The canonical source of truth is `knowledge/taxonomy.yaml`. Layer definition files in `knowledge/layers/` document boundaries and ownership. + +### Four-Level Hierarchy + +| Level | Stage Field | Service Field | Purpose | +|-------|------------|---------------|---------| +| **Layer** | `stage.layer` | — | Top-level architectural boundary | +| **Capability** | `stage.capability` | — | Sub-classification within a layer | +| **Component** | — | `service.component` | Functional role within a capability | +| **Resource** | — | `service.resource_type` | Azure resource type or code artifact | + +### Layers and Capabilities + +| Layer | Owner | Capabilities | +|-------|-------|-------------| +| **Core** | `cloud-architect` | `identity`, `observability` | +| **Infrastructure** | `infrastructure-architect` | `core-networking`, `compute`, `security`, `ai-services`, `supporting` | +| **Data** | `data-architect` | `data-services`, `storage-services`, `messaging` | +| **Application** | `application-architect` | `presentation`, `domain`, `data-access`, `background` | +| **Docs** | `doc-agent` | `documentation` | + +### Service Placement Rules + +- **Infrastructure provisions, Application consumes.** Infrastructure layer creates the Azure resource (e.g., Service Bus namespace via IaC). Application layer creates the code that uses it (e.g., `IMessageSender` interface). Data layer owns the data model (schemas, indexes, partition keys). +- **Networking is centralized.** All private endpoints, DNS zones, and VNet resources belong in a single Networking stage (capability: `core-networking`) within the Infrastructure layer. +- **Core deploys first.** Identity and observability must exist before any other layer can configure RBAC or diagnostics. +- **Data deploys before Application.** Application code depends on data service endpoints being available. +- **1:1 stage-to-capability.** Each stage has exactly one capability. Multiple stages can share the same capability. +- **Key Vault is Infrastructure/Security.** Not Data layer — it's `infra` / `security` / `secrets-management`. +- **APIM is Infrastructure/Core Networking.** It's an API-level ingress controller — `infra` / `core-networking` / `api-gateway`. +- **IoT Hub and Event Grid are Data/Messaging.** Data ingestion and event routing — `data` / `messaging`. + +--- + +## 11. Direct Execution Policy This extension **executes deployment commands directly** (`terraform apply`, `az deployment group create`, etc.) rather than generating commands for a human to run. diff --git a/azext_prototype/knowledge/languages/python.md b/azext_prototype/knowledge/languages/python.md index 70a839d..423e802 100644 --- a/azext_prototype/knowledge/languages/python.md +++ b/azext_prototype/knowledge/languages/python.md @@ -662,3 +662,68 @@ markers = [ "integration: marks tests requiring live Azure resources", ] ``` + +## Common Pitfalls + +### NEVER instantiate clients at module level +```python +# WRONG — fails at import time if env vars are missing +engine = create_engine(os.environ["DATABASE_URL"]) # crashes on import + +# CORRECT — use FastAPI lifespan or dependency injection +@asynccontextmanager +async def lifespan(app: FastAPI): + app.state.engine = create_engine(os.environ["DATABASE_URL"]) + yield + app.state.engine.dispose() +``` + +### NEVER use mutable default parameters for service instances +```python +# WRONG — service instance shared across all calls, created at function definition time +def get_orders(service: OrderService = OrderService()): + return service.list() + +# CORRECT — use FastAPI Depends() +def get_orders(service: OrderService = Depends(get_order_service)): + return service.list() +``` + +### NEVER use `hmac.new` — it does not exist +```python +# WRONG — hmac.new is not a Python function +signature = hmac.new(key, msg, hashlib.sha256).hexdigest() + +# CORRECT — use hmac.new → hmac.HMAC or the shorthand hmac.digest +signature = hmac.HMAC(key, msg, hashlib.sha256).hexdigest() +# Or for one-shot: +signature = hmac.digest(key, msg, "sha256").hex() +``` + +### Use Protocol classes for interfaces +```python +# Define contracts between sub-layers using Protocol +from typing import Protocol + +class OrderRepository(Protocol): + async def get(self, order_id: str) -> Order | None: ... + async def save(self, order: Order) -> None: ... + +# Implementation depends on the protocol, not the concrete class +class OrderService: + def __init__(self, repo: OrderRepository) -> None: + self._repo = repo +``` + +### Pin dependencies with version ranges +``` +# WRONG — unpinned, breaks on major version changes +fastapi +uvicorn +azure-identity + +# CORRECT — pinned major version +fastapi>=0.115,<1.0 +uvicorn>=0.32,<1.0 +azure-identity>=1.19,<2.0 +``` diff --git a/azext_prototype/knowledge/languages/react.md b/azext_prototype/knowledge/languages/react.md new file mode 100644 index 0000000..d43b1b7 --- /dev/null +++ b/azext_prototype/knowledge/languages/react.md @@ -0,0 +1,827 @@ +# React/TypeScript Language Patterns for Azure Prototypes + +Reference patterns for React/TypeScript-based Azure prototype frontends. Agents should use these patterns when generating React frontend code. + +## Project Structure + +``` +apps/ +└── web/ + ├── src/ + │ ├── main.tsx # App entry point (React.createRoot) + │ ├── App.tsx # Root component — providers, router + │ ├── vite-env.d.ts # Vite environment type declarations + │ ├── auth/ + │ │ ├── authConfig.ts # MSAL configuration (clientId, authority, scopes) + │ │ └── AuthProvider.tsx # MsalProvider wrapper + │ ├── components/ + │ │ ├── layout/ # Layout shell (Header, Sidebar, Footer, PageLayout) + │ │ ├── common/ # Reusable UI (Button, Card, Modal, LoadingSpinner, ErrorBanner) + │ │ └── features/ # Feature-specific components grouped by domain + │ ├── pages/ # Route-level page components (one per route) + │ ├── hooks/ # Custom hooks (useApi, useAuth, useSignalR, useDebounce) + │ ├── services/ # API client functions — typed request/response + │ ├── types/ # Shared TypeScript interfaces and type definitions + │ └── utils/ # Pure helper functions (formatting, validation) + ├── public/ + │ └── favicon.svg + ├── index.html # Vite HTML entry point + ├── vite.config.ts # Vite configuration + ├── tsconfig.json # TypeScript strict configuration + ├── tailwind.config.js # Tailwind CSS configuration + ├── postcss.config.js # PostCSS for Tailwind + ├── package.json + ├── .env.example # Required environment variables + └── Dockerfile # Multi-stage build (node build -> nginx serve) +``` + +### Folder conventions +- `components/` contains reusable pieces; `pages/` contains route-level compositions +- `hooks/` contains only custom React hooks (prefixed with `use`) +- `services/` contains API call functions, never React components or hooks +- `types/` contains shared interfaces; component-specific types live next to their component +- One component per file; filename matches the default export name + +## Vite Build Tooling + +### vite.config.ts +```typescript +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + plugins: [react()], + server: { + port: 3000, + proxy: { + "/api": { + target: "http://localhost:8080", + changeOrigin: true, + }, + }, + }, + build: { + outDir: "dist", + sourcemap: true, + }, +}); +``` + +### Environment Variables + +All frontend environment variables MUST use the `VITE_` prefix. They are embedded at build time, not runtime secrets. + +```bash +# .env.example +VITE_API_BASE_URL=http://localhost:8080 +VITE_AZURE_CLIENT_ID= +VITE_AZURE_TENANT_ID= +VITE_API_SCOPE=api:///access_as_user +VITE_SIGNALR_URL=http://localhost:8080/hub +``` + +Access in code via `import.meta.env`: + +```typescript +const apiBaseUrl = import.meta.env.VITE_API_BASE_URL; +const clientId = import.meta.env.VITE_AZURE_CLIENT_ID; +``` + +### vite-env.d.ts +```typescript +/// + +interface ImportMetaEnv { + readonly VITE_API_BASE_URL: string; + readonly VITE_AZURE_CLIENT_ID: string; + readonly VITE_AZURE_TENANT_ID: string; + readonly VITE_API_SCOPE: string; + readonly VITE_SIGNALR_URL?: string; +} + +interface ImportMeta { + readonly env: ImportMetaEnv; +} +``` + +## MSAL React Authentication + +### authConfig.ts +```typescript +import { Configuration, LogLevel } from "@azure/msal-browser"; + +export const msalConfig: Configuration = { + auth: { + clientId: import.meta.env.VITE_AZURE_CLIENT_ID, + authority: `https://login.microsoftonline.com/${import.meta.env.VITE_AZURE_TENANT_ID}`, + redirectUri: window.location.origin, + postLogoutRedirectUri: window.location.origin, + }, + cache: { + cacheLocation: "sessionStorage", + storeAuthStateInCookie: false, + }, + system: { + loggerOptions: { + logLevel: LogLevel.Warning, + loggerCallback: (level, message) => { + if (level === LogLevel.Error) console.error(message); + }, + }, + }, +}; + +export const loginRequest = { + scopes: [import.meta.env.VITE_API_SCOPE], +}; + +export const apiScopes = [import.meta.env.VITE_API_SCOPE]; +``` + +### AuthProvider.tsx +```typescript +import { MsalProvider } from "@azure/msal-react"; +import { PublicClientApplication, EventType, EventMessage, AuthenticationResult } from "@azure/msal-browser"; +import { msalConfig } from "./authConfig"; + +const msalInstance = new PublicClientApplication(msalConfig); + +// Set the first account as active on login +msalInstance.addEventCallback((event: EventMessage) => { + if (event.eventType === EventType.LOGIN_SUCCESS && event.payload) { + const result = event.payload as AuthenticationResult; + msalInstance.setActiveAccount(result.account); + } +}); + +interface AuthProviderProps { + children: React.ReactNode; +} + +export function AuthProvider({ children }: AuthProviderProps) { + return {children}; +} +``` + +### App.tsx with authentication +```typescript +import { BrowserRouter, Routes, Route } from "react-router-dom"; +import { AuthenticatedTemplate, UnauthenticatedTemplate } from "@azure/msal-react"; +import { AuthProvider } from "./auth/AuthProvider"; +import { PageLayout } from "./components/layout/PageLayout"; +import { LoginPage } from "./pages/LoginPage"; +import { HomePage } from "./pages/HomePage"; +import { DashboardPage } from "./pages/DashboardPage"; + +export default function App() { + return ( + + + + + + + + + } /> + } /> + + + + + + ); +} +``` + +## React Router Navigation + +```typescript +// pages/ — one component per route +import { useNavigate, useParams } from "react-router-dom"; + +export function OrderDetailPage() { + const { orderId } = useParams<{ orderId: string }>(); + const navigate = useNavigate(); + + const handleBack = () => navigate("/orders"); + + return ( +
+ +

Order: {orderId}

+ {/* ... */} +
+ ); +} +``` + +Route definitions in `App.tsx`: +```typescript + + } /> + } /> + } /> + } /> + +``` + +## API Client Pattern + +The frontend NEVER accesses Azure services directly. All data flows through backend API endpoints. + +### useApi hook (authenticated fetch) +```typescript +// hooks/useApi.ts +import { useMsal } from "@azure/msal-react"; +import { apiScopes } from "../auth/authConfig"; + +const API_BASE = import.meta.env.VITE_API_BASE_URL; + +export function useApi() { + const { instance } = useMsal(); + + async function callApi( + path: string, + options: RequestInit = {} + ): Promise { + const account = instance.getActiveAccount(); + if (!account) throw new Error("No active account. User must sign in."); + + const tokenResponse = await instance.acquireTokenSilent({ + scopes: apiScopes, + account, + }); + + const response = await fetch(`${API_BASE}${path}`, { + ...options, + headers: { + Authorization: `Bearer ${tokenResponse.accessToken}`, + "Content-Type": "application/json", + ...options.headers, + }, + }); + + if (!response.ok) { + const errorBody = await response.json().catch(() => ({})); + throw new ApiError(response.status, errorBody.error || response.statusText); + } + + return response.json(); + } + + return { callApi }; +} + +export class ApiError extends Error { + constructor( + public status: number, + message: string + ) { + super(message); + this.name = "ApiError"; + } +} +``` + +### Typed service functions +```typescript +// services/orderService.ts +import type { Order, CreateOrderRequest } from "../types"; + +export function createOrderService(callApi: (path: string, options?: RequestInit) => Promise) { + return { + async listOrders(): Promise { + return callApi("/api/v1/orders"); + }, + + async getOrder(id: string): Promise { + return callApi(`/api/v1/orders/${id}`); + }, + + async createOrder(data: CreateOrderRequest): Promise { + return callApi("/api/v1/orders", { + method: "POST", + body: JSON.stringify(data), + }); + }, + + async deleteOrder(id: string): Promise { + await callApi(`/api/v1/orders/${id}`, { method: "DELETE" }); + }, + }; +} +``` + +### Usage in a component +```typescript +import { useState, useEffect } from "react"; +import { useApi } from "../hooks/useApi"; +import { createOrderService } from "../services/orderService"; +import type { Order } from "../types"; + +export function OrderListPage() { + const { callApi } = useApi(); + const orderService = createOrderService(callApi); + const [orders, setOrders] = useState([]); + const [loading, setLoading] = useState(true); + const [error, setError] = useState(null); + + useEffect(() => { + orderService + .listOrders() + .then(setOrders) + .catch((err) => setError(err.message)) + .finally(() => setLoading(false)); + }, []); + + if (loading) return ; + if (error) return ; + + return ( +
+

Orders

+ {orders.map((order) => ( + + ))} +
+ ); +} +``` + +## SignalR Real-Time Updates + +When the backend uses Azure SignalR Service: + +```typescript +// hooks/useSignalR.ts +import { useEffect, useRef, useCallback } from "react"; +import { HubConnectionBuilder, HubConnection, LogLevel } from "@microsoft/signalr"; +import { useMsal } from "@azure/msal-react"; +import { apiScopes } from "../auth/authConfig"; + +const SIGNALR_URL = import.meta.env.VITE_SIGNALR_URL; + +export function useSignalR(hubPath: string = "/hub") { + const { instance } = useMsal(); + const connectionRef = useRef(null); + + useEffect(() => { + if (!SIGNALR_URL) return; + + const connection = new HubConnectionBuilder() + .withUrl(`${SIGNALR_URL}${hubPath}`, { + accessTokenFactory: async () => { + const account = instance.getActiveAccount(); + if (!account) return ""; + const token = await instance.acquireTokenSilent({ + scopes: apiScopes, + account, + }); + return token.accessToken; + }, + }) + .withAutomaticReconnect() + .configureLogging(LogLevel.Warning) + .build(); + + connection.start().catch((err) => console.error("SignalR connection failed:", err)); + connectionRef.current = connection; + + return () => { + connection.stop(); + }; + }, [hubPath, instance]); + + const on = useCallback( + (eventName: string, callback: (...args: unknown[]) => void) => { + connectionRef.current?.on(eventName, callback); + return () => connectionRef.current?.off(eventName, callback); + }, + [] + ); + + return { on, connection: connectionRef.current }; +} +``` + +Usage: +```typescript +export function NotificationPanel() { + const { on } = useSignalR(); + const [notifications, setNotifications] = useState([]); + + useEffect(() => { + return on("NewNotification", (message: unknown) => { + setNotifications((prev) => [String(message), ...prev]); + }); + }, [on]); + + return ( +
    + {notifications.map((msg, i) => ( +
  • {msg}
    • + ))} +
+ ); +} +``` + +## TypeScript Configuration + +```json +{ + "compilerOptions": { + "target": "ES2020", + "lib": ["ES2020", "DOM", "DOM.Iterable"], + "module": "ESNext", + "moduleResolution": "bundler", + "jsx": "react-jsx", + "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noFallthroughCasesInSwitch": true, + "skipLibCheck": true, + "esModuleInterop": true, + "resolveJsonModule": true, + "isolatedModules": true, + "forceConsistentCasingInFileNames": true, + "allowImportingTsExtensions": true, + "noEmit": true + }, + "include": ["src"], + "references": [{ "path": "./tsconfig.node.json" }] +} +``` + +## Component Patterns + +### Props interfaces +```typescript +// Always define a Props interface for every component +interface OrderCardProps { + order: Order; + onSelect?: (orderId: string) => void; + className?: string; +} + +export function OrderCard({ order, onSelect, className }: OrderCardProps) { + return ( +
onSelect?.(order.id)}> +

{order.title}

+

{order.status}

+
+ ); +} +``` + +### Error boundaries +```typescript +// components/common/ErrorBoundary.tsx +import { Component, type ErrorInfo, type ReactNode } from "react"; + +interface ErrorBoundaryProps { + children: ReactNode; + fallback?: ReactNode; +} + +interface ErrorBoundaryState { + hasError: boolean; + error: Error | null; +} + +export class ErrorBoundary extends Component { + state: ErrorBoundaryState = { hasError: false, error: null }; + + static getDerivedStateFromError(error: Error) { + return { hasError: true, error }; + } + + componentDidCatch(error: Error, info: ErrorInfo) { + console.error("ErrorBoundary caught:", error, info); + } + + render() { + if (this.state.hasError) { + return ( + this.props.fallback ?? ( +
+

Something went wrong

+

{this.state.error?.message}

+
+ ) + ); + } + return this.props.children; + } +} +``` + +### Code splitting with React.lazy +```typescript +import { lazy, Suspense } from "react"; +import { LoadingSpinner } from "./components/common/LoadingSpinner"; + +const DashboardPage = lazy(() => import("./pages/DashboardPage")); +const SettingsPage = lazy(() => import("./pages/SettingsPage")); + +// In routes: +}> + + } /> + } /> + + +``` + +## Dockerfile (Multi-Stage: Node Build + Nginx Serve) + +```dockerfile +# Stage 1: Build +FROM node:20-alpine AS builder + +WORKDIR /build +COPY package.json package-lock.json ./ +RUN npm ci +COPY . . + +# Build-time environment variables (baked into the bundle) +ARG VITE_API_BASE_URL +ARG VITE_AZURE_CLIENT_ID +ARG VITE_AZURE_TENANT_ID +ARG VITE_API_SCOPE + +RUN npm run build + +# Stage 2: Serve with nginx +FROM nginx:1.27-alpine AS runtime + +# Remove default nginx config +RUN rm /etc/nginx/conf.d/default.conf + +# Copy custom nginx config for SPA routing +COPY nginx.conf /etc/nginx/conf.d/default.conf + +# Copy built assets +COPY --from=builder /build/dist /usr/share/nginx/html + +# Non-root user (nginx alpine image supports this) +RUN chown -R nginx:nginx /usr/share/nginx/html + +EXPOSE 80 + +HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ + CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1 + +CMD ["nginx", "-g", "daemon off;"] +``` + +### nginx.conf (SPA routing) +```nginx +server { + listen 80; + server_name _; + root /usr/share/nginx/html; + index index.html; + + # SPA routing — serve index.html for all non-file routes + location / { + try_files $uri $uri/ /index.html; + } + + # Health check endpoint + location /health { + access_log off; + return 200 '{"status":"healthy"}'; + add_header Content-Type application/json; + } + + # Cache static assets aggressively + location /assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + + # Security headers + add_header X-Content-Type-Options "nosniff" always; + add_header X-Frame-Options "DENY" always; + add_header Referrer-Policy "strict-origin-when-cross-origin" always; +} +``` + +## Health / Readiness + +Health checks are not applicable to the React frontend in the traditional sense (it is a static SPA served by nginx). However: + +- The nginx container exposes `/health` returning `{"status":"healthy"}` for container orchestrator liveness probes +- The Dockerfile includes a `HEALTHCHECK` instruction +- The frontend itself does NOT expose health endpoints -- it is a static asset bundle + +## package.json + +```json +{ + "name": "prototype-web", + "private": true, + "version": "0.1.0", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc && vite build", + "preview": "vite preview", + "lint": "eslint src/", + "lint:fix": "eslint src/ --fix", + "test": "vitest run", + "test:watch": "vitest" + }, + "dependencies": { + "react": "^18.3.0", + "react-dom": "^18.3.0", + "react-router-dom": "^6.28.0", + + "@azure/msal-browser": "^3.27.0", + "@azure/msal-react": "^2.1.0", + + "@microsoft/signalr": "^8.0.0" + }, + "devDependencies": { + "@types/react": "^18.3.0", + "@types/react-dom": "^18.3.0", + "@vitejs/plugin-react": "^4.3.0", + "typescript": "^5.7.0", + "vite": "^6.0.0", + + "tailwindcss": "^3.4.0", + "postcss": "^8.4.0", + "autoprefixer": "^10.4.0", + + "vitest": "^2.1.0", + "@testing-library/react": "^16.1.0", + "@testing-library/jest-dom": "^6.6.0", + "@testing-library/user-event": "^14.5.0", + + "eslint": "^9.16.0", + "@typescript-eslint/eslint-plugin": "^8.18.0", + "@typescript-eslint/parser": "^8.18.0", + "eslint-plugin-react-hooks": "^5.0.0" + } +} +``` + +## Testing Patterns (Vitest + React Testing Library) + +### vitest.config.ts +```typescript +import { defineConfig } from "vitest/config"; +import react from "@vitejs/plugin-react"; + +export default defineConfig({ + plugins: [react()], + test: { + globals: true, + environment: "jsdom", + setupFiles: ["./src/test/setup.ts"], + css: false, + }, +}); +``` + +### Test setup +```typescript +// src/test/setup.ts +import "@testing-library/jest-dom/vitest"; +import { vi } from "vitest"; + +// Mock MSAL +vi.mock("@azure/msal-react", () => ({ + useMsal: () => ({ + instance: { + getActiveAccount: () => ({ username: "test@example.com" }), + acquireTokenSilent: vi.fn().mockResolvedValue({ accessToken: "mock-token" }), + }, + accounts: [{ username: "test@example.com" }], + }), + MsalProvider: ({ children }: { children: React.ReactNode }) => children, + AuthenticatedTemplate: ({ children }: { children: React.ReactNode }) => children, + UnauthenticatedTemplate: () => null, +})); + +// Mock import.meta.env +vi.stubEnv("VITE_API_BASE_URL", "http://localhost:8080"); +vi.stubEnv("VITE_AZURE_CLIENT_ID", "test-client-id"); +vi.stubEnv("VITE_AZURE_TENANT_ID", "test-tenant-id"); +vi.stubEnv("VITE_API_SCOPE", "api://test/access_as_user"); +``` + +### Component test +```typescript +// src/components/features/__tests__/OrderCard.test.tsx +import { render, screen, fireEvent } from "@testing-library/react"; +import { describe, it, expect, vi } from "vitest"; +import { OrderCard } from "../OrderCard"; + +describe("OrderCard", () => { + const mockOrder = { + id: "order-1", + title: "Test Order", + status: "Pending", + }; + + it("renders order details", () => { + render(); + expect(screen.getByText("Test Order")).toBeInTheDocument(); + expect(screen.getByText("Pending")).toBeInTheDocument(); + }); + + it("calls onSelect when clicked", () => { + const onSelect = vi.fn(); + render(); + fireEvent.click(screen.getByText("Test Order")); + expect(onSelect).toHaveBeenCalledWith("order-1"); + }); +}); +``` + +### API hook test +```typescript +// src/hooks/__tests__/useApi.test.tsx +import { renderHook } from "@testing-library/react"; +import { describe, it, expect, vi, beforeEach } from "vitest"; +import { useApi } from "../useApi"; + +describe("useApi", () => { + beforeEach(() => { + vi.restoreAllMocks(); + }); + + it("attaches bearer token to requests", async () => { + const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue( + new Response(JSON.stringify({ id: "1" }), { status: 200 }) + ); + + const { result } = renderHook(() => useApi()); + await result.current.callApi("/api/v1/items"); + + expect(fetchSpy).toHaveBeenCalledWith( + expect.stringContaining("/api/v1/items"), + expect.objectContaining({ + headers: expect.objectContaining({ + Authorization: "Bearer mock-token", + }), + }) + ); + }); +}); +``` + +## Common Pitfalls + +### NEVER use `require()` in test files — Vitest uses ESM +```typescript +// WRONG — require() bypasses Vitest module mocks +const { reducer } = require("./boardReducer"); + +// CORRECT — use import (ESM) +import { reducer } from "./boardReducer"; +``` + +### NEVER use dynamic `import()` inside test bodies +```typescript +// WRONG — dynamic import bypasses Vitest mock cache +it("should work", async () => { + const { useApi } = await import("../hooks/useApi"); // mock not applied +}); + +// CORRECT — import at top level, mock at module level +import { useApi } from "../hooks/useApi"; +vi.mock("../hooks/useApi"); +``` + +### Use ConnectionString, NOT InstrumentationKey +```typescript +// WRONG — InstrumentationKey is deprecated +VITE_APPLICATIONINSIGHTS_KEY=00000000-0000-0000-0000-000000000000 + +// CORRECT — use ConnectionString +VITE_APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...;IngestionEndpoint=... +``` + +### Always mock MSAL at the module level +```typescript +// In test setup (src/test/setup.ts), NOT in individual tests +vi.mock("@azure/msal-react", () => ({ + useMsal: () => ({ + instance: { getActiveAccount: () => ({ username: "test@test.com" }) }, + }), +})); +``` + +## Critical Rules + +1. **NEVER access Azure services directly** -- no Azure SDK imports in frontend code. All data flows through backend API endpoints with authentication. +2. **Use MSAL for authentication** -- `@azure/msal-react` and `@azure/msal-browser`. Tokens are sent as `Bearer` in API calls. +3. **No secrets in frontend code** -- environment variables are baked into the build and are publicly visible. Only store client IDs, tenant IDs, API scopes, and endpoint URLs. +4. **Use `import.meta.env.VITE_*`** for all configuration -- never hardcode URLs, client IDs, or API paths. +5. **TypeScript strict mode** -- `"strict": true` in `tsconfig.json`. Define interfaces for all props, API responses, and state. +6. **Functional components only** -- no class components except for Error Boundaries (React limitation). +7. **Do NOT generate backend, IaC, or deployment scripts** -- this language pattern is frontend only. diff --git a/azext_prototype/knowledge/layers/__init__.py b/azext_prototype/knowledge/layers/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/azext_prototype/knowledge/layers/application.md b/azext_prototype/knowledge/layers/application.md new file mode 100644 index 0000000..124782e --- /dev/null +++ b/azext_prototype/knowledge/layers/application.md @@ -0,0 +1,108 @@ +# Application Layer + +The layer responsible for all application source code. Owned by the `application-architect`, implemented by language-specific developers (`csharp-developer`, `python-developer`, `react-developer`). + +## Owner + +- **Primary**: `application-architect` +- **Delegates to**: `csharp-developer`, `python-developer`, `react-developer` (based on technology choices from discovery) +- **Security review**: `security-architect` reviews authentication flows, secret handling, input validation + +## Sub-Layers + +Every application stage is decomposed into distinct sub-layers. The application-architect assigns each sub-layer to the appropriate developer based on the architecture's technology choices. + +### 1. Presentation + +UI and frontend code. Framework depends on architecture choices (not hardcoded): + +- React/TypeScript frontend -> `react-developer` +- Blazor / .NET MVC -> `csharp-developer` +- Python web framework (Flask, Django templates) -> `python-developer` + +**Produces**: Pages, components, routing, static assets, client-side state management. + +### 2. Services / API + +API endpoints and controllers that expose business logic: + +- ASP.NET Core Web API -> `csharp-developer` +- FastAPI / Flask -> `python-developer` +- Express.js -> `react-developer` (Node.js) + +**Produces**: API controllers/routes, request/response models, middleware, OpenAPI specs. + +### 3. Business Logic + +Domain logic, validation rules, and business workflows: + +- Same language as the API layer (shared codebase) + +**Produces**: Domain models, validation logic, business rule implementations, workflow orchestrators. + +### 4. Data Access + +Repository pattern, ORM mappings, and database query logic: + +- Entity Framework Core -> `csharp-developer` +- SQLAlchemy / motor (async MongoDB) -> `python-developer` +- Prisma / TypeORM -> `react-developer` (Node.js) + +**Produces**: Repository interfaces and implementations, ORM entity mappings, migration scripts, query builders. + +### 5. Background / Auxiliary + +DI-injected cross-cutting concerns and background services: + +- Logging abstractions (`ILogger`, OpenTelemetry SDK) +- Messaging interfaces (`IMessageSender`, queue processors) +- External service clients (HTTP clients, SDK wrappers) +- Background workers (hosted services, queue listeners) + +**Important**: These are the *application-side abstractions* that interact with Azure resources. The Azure resources themselves (Service Bus namespace, Storage Account) are provisioned by the Infrastructure and Data layers -- not here. + +**Produces**: Interface definitions, DI registration, background service implementations, configuration binding. + +## What Does NOT Belong Here + +- **Azure resource provisioning** (IaC) -- that is Infrastructure or Data layer +- **Network configuration** -- that is Infrastructure layer +- **Database schema creation** (via IaC) -- that is Data layer (but migration scripts in code ARE Application layer) +- **Deployment scripts** for infrastructure -- that is Infrastructure layer + +## Key Boundary: Application Code vs Infrastructure + +Application layer generates *source code* that runs on compute resources. It does NOT generate Terraform/Bicep. Application stages produce: + +- Source files (`.cs`, `.py`, `.tsx`, `.ts`, `.js`) +- Project files (`*.csproj`, `requirements.txt`, `package.json`) +- Dockerfiles and container configuration +- Build and deploy scripts (`deploy.sh` for build+push+update) +- Configuration files (`appsettings.json`, `.env.example`) + +Infrastructure references (endpoints, connection strings, secrets) come from environment variables injected at deploy time by the compute platform (Container Apps settings, App Service configuration), NOT from `terraform_remote_state`. + +## Deployment Order + +Application deploys **last** (before Documentation), after all infrastructure and data services are provisioned: + +1. All Core, Infrastructure, and Data stages must complete first +2. Each application stage builds and deploys one deployable unit +3. Multiple app stages run in sequence (API before frontend if frontend calls API) + +## Inter-Layer Communication + +| Provider | What Application Consumes | +|----------|--------------------------| +| Core | Application Insights connection string (for telemetry) | +| Infrastructure | Container registry login server (for image push), compute endpoint URLs | +| Data | Database connection endpoints, Key Vault URIs, messaging endpoints | + +## Governance + +- No hardcoded secrets in source code -- use environment variables backed by Key Vault references +- Use managed identity credential libraries (`DefaultAzureCredential`) for all Azure service access +- Follow the project's language-specific standards (STAN-PY, STAN-CS, STAN-CODE) +- Every deployable must include a Dockerfile and `deploy.sh` script +- API endpoints must validate input and return proper error responses +- Background services must handle graceful shutdown diff --git a/azext_prototype/knowledge/layers/core.md b/azext_prototype/knowledge/layers/core.md new file mode 100644 index 0000000..b99fac7 --- /dev/null +++ b/azext_prototype/knowledge/layers/core.md @@ -0,0 +1,56 @@ +# Core Layer + +The foundational layer that all other layers depend on. Owned exclusively by the `cloud-architect`. + +## Owner + +- **Primary**: `cloud-architect` +- **No delegation** -- the cloud-architect directly manages all Core Layer concerns + +## Services + +Core Layer services are cross-cutting foundations, not individual Azure resources: + +| Concern | Examples | +|---------|----------| +| Management Groups & Subscriptions | Resource group strategy, subscription alignment | +| Regions & Availability | Primary/secondary regions, zone selection | +| Naming Conventions | Project naming strategy applied to all resources | +| Security & Identity | Managed identity (user-assigned), Entra ID configuration | +| Observability Foundation | Log Analytics workspace, Application Insights | + +### ARM Namespaces in This Layer + +- `Microsoft.ManagedIdentity/userAssignedIdentities` +- `Microsoft.OperationalInsights/workspaces` +- `Microsoft.Insights/components` (Application Insights) + +## What Does NOT Belong Here + +- **Network resources** -- VNets, subnets, NSGs, private endpoints belong in the Infrastructure layer +- **Data services** -- databases, storage, messaging belong in the Data layer +- **Compute resources** -- Container Apps, App Service, Functions belong in the Infrastructure layer +- **Application code** -- all source code belongs in the Application layer + +## Deployment Order + +Core deploys **first**. All other layers depend on Core outputs: + +- `principal_id` from managed identity (used for RBAC in every downstream stage) +- `workspace_id` from Log Analytics (used for diagnostic settings in every downstream stage) +- `instrumentation_key` / `connection_string` from Application Insights + +## Inter-Layer Communication + +| Consumer | What Core Provides | +|----------|-------------------| +| Infrastructure | Managed identity principal_id for RBAC, Log Analytics workspace_id for diagnostics | +| Data | Same as Infrastructure -- identity for data-plane RBAC, workspace for diagnostics | +| Application | Application Insights connection string for telemetry | + +## Governance + +- All resources must follow the project naming strategy +- Managed identity is mandatory -- no service principal secrets for service-to-service auth +- Log Analytics workspace must be created before any resource that emits diagnostics +- Application Insights must use workspace-based mode (not classic) diff --git a/azext_prototype/knowledge/layers/data.md b/azext_prototype/knowledge/layers/data.md new file mode 100644 index 0000000..a5fd599 --- /dev/null +++ b/azext_prototype/knowledge/layers/data.md @@ -0,0 +1,100 @@ +# Data Layer + +The layer responsible for all data services, schemas, and access patterns. Owned by the `data-architect`, with IaC implemented by `terraform-agent` or `bicep-agent`. + +## Owner + +- **Primary**: `data-architect` +- **Delegates to**: `terraform-agent` or `bicep-agent` for Azure resource provisioning +- **Security review**: `security-architect` reviews data-plane security (RBAC, encryption, access patterns) + +## Service Categories + +### Relational Databases + +- Azure SQL Server and databases +- PostgreSQL Flexible Server +- MySQL Flexible Server + +**ARM Namespaces**: `Microsoft.Sql/*`, `Microsoft.DBforPostgreSQL/*`, `Microsoft.DBforMySQL/*` + +### NoSQL / Document Databases + +- Cosmos DB (all APIs: SQL, MongoDB, Cassandra, Gremlin, Table) + +**ARM Namespaces**: `Microsoft.DocumentDB/*` + +### Caching + +- Azure Cache for Redis + +**ARM Namespaces**: `Microsoft.Cache/*` + +### Storage + +- Storage Accounts (Blob, Table, Queue, File, Data Lake) + +**ARM Namespaces**: `Microsoft.Storage/*` + +### Messaging & Streaming + +- Service Bus (namespaces, queues, topics) +- Event Hubs (namespaces, event hubs, consumer groups) + +**ARM Namespaces**: `Microsoft.ServiceBus/*`, `Microsoft.EventHub/*` + +### Data Processing + +- Azure Databricks +- Azure Data Factory +- Azure Synapse Analytics + +**ARM Namespaces**: `Microsoft.Databricks/*`, `Microsoft.DataFactory/*`, `Microsoft.Synapse/*` + +### Secrets & Configuration + +- Azure Key Vault (vaults, secrets, keys, certificates) + +**ARM Namespaces**: `Microsoft.KeyVault/*` + +## What Does NOT Belong Here + +- **Network resources** for data services (private endpoints, DNS zones) -- those are Infrastructure layer +- **Application code** that reads/writes data (repositories, ORMs, query logic) -- that is Application layer (data access sub-layer) +- **Compute resources** that process data (Functions, Container Apps) -- those are Infrastructure layer +- **Observability** (Log Analytics, App Insights) -- those are Core layer + +## Key Boundary: Data Service vs Data Access + +The Data layer provisions the Azure data resource (e.g., creates a Cosmos DB account, database, and container via IaC) and defines the data model (schemas, indexes, partition keys). The Application layer's *data access sub-layer* contains the code that interacts with these resources (e.g., repository classes, ORM mappings, query builders). + +## Deployment Order + +Data deploys **after Core and Networking**, before Application: + +1. **Key Vault** -- first, because other data services may store secrets in it +2. **Databases** -- SQL, Cosmos, PostgreSQL, etc. +3. **Storage** -- Storage Accounts +4. **Messaging** -- Service Bus, Event Hubs +5. **Data Processing** -- Databricks, Data Factory (if present) + +Each data stage references: +- Core outputs: managed identity principal_id (for RBAC), Log Analytics workspace_id (for diagnostics) +- Networking outputs: private endpoint connectivity (created by Infrastructure layer) + +## Inter-Layer Communication + +| Consumer | What Data Provides | +|----------|-------------------| +| Application | Connection endpoints, Key Vault secret URIs, database connection metadata | +| Infrastructure | (Data does not typically provide to Infrastructure -- dependency flows downward) | +| Core | (Data does not provide to Core) | + +## Governance + +- All data services must use Entra-based authentication (managed identity RBAC, no connection strings with keys) +- Cosmos DB data-plane roles must use `sqlRoleAssignments`, not ARM `roleAssignments` +- Key Vault must use RBAC authorization model (not access policies) +- Encryption at rest must be enabled (service-managed keys minimum) +- TLS 1.2+ required for all data service connections +- Key Vault should deploy first among data services (other services reference its secrets) diff --git a/azext_prototype/knowledge/layers/infrastructure.md b/azext_prototype/knowledge/layers/infrastructure.md new file mode 100644 index 0000000..b99c3fa --- /dev/null +++ b/azext_prototype/knowledge/layers/infrastructure.md @@ -0,0 +1,91 @@ +# Infrastructure Layer + +The layer responsible for provisioning all Azure resources via IaC. Owned by the `infrastructure-architect`, implemented by `terraform-agent` or `bicep-agent`. + +## Owner + +- **Primary**: `infrastructure-architect` +- **Delegates to**: `terraform-agent` (Terraform projects) or `bicep-agent` (Bicep projects) +- **Security review**: `security-architect` reviews all infrastructure stages + +## Service Categories + +### Core Networking + +Azure resources that form the network foundation: + +- Virtual Networks (VNets), subnets +- Network Security Groups (NSGs) +- VNet peering, VPN/ExpressRoute gateways +- Load balancers (public and internal) +- Private endpoints and private DNS zones +- Azure Firewall, Application Gateway, Front Door +- Azure Bastion + +**ARM Namespaces**: `Microsoft.Network/*` + +### Compute Services + +Azure resources that host application workloads: + +- Container Apps environments and container apps +- App Service plans and web apps +- Azure Functions +- Azure Kubernetes Service (AKS) +- Container Registry +- Static Web Apps + +**ARM Namespaces**: `Microsoft.App/*`, `Microsoft.Web/*`, `Microsoft.ContainerService/*`, `Microsoft.ContainerRegistry/*` + +### Supporting Services + +Azure resources that support application functionality but are not data stores: + +- API Management +- Event Grid +- IoT Hub +- Notification Hubs +- Communication Services +- Azure AI / Cognitive Services +- Azure OpenAI +- Azure Search + +**ARM Namespaces**: `Microsoft.ApiManagement/*`, `Microsoft.EventGrid/*`, `Microsoft.CognitiveServices/*`, `Microsoft.Search/*`, etc. + +## What Does NOT Belong Here + +- **Managed identity and observability foundations** -- those are Core layer (cloud-architect) +- **Database schemas, stored procedures, seed data** -- those are Data layer +- **Application source code** (APIs, workers, frontends, Dockerfiles) -- those are Application layer +- **Data service configuration beyond provisioning** -- Infrastructure provisions the Azure resource; Data layer owns the data model + +## Key Boundary: Provisioning vs Usage + +Infrastructure layer provisions the Azure resource (e.g., creates a Service Bus namespace via IaC). The Application layer creates the code that *uses* that resource (e.g., the `IMessageSender` interface). The Data layer owns data schemas and access patterns (e.g., SQL tables, Cosmos containers). + +## Deployment Order + +Infrastructure deploys **after Core**, in this order: + +1. **Networking** -- VNet, subnets, NSGs, private DNS zones, private endpoints (one stage) +2. **Compute infrastructure** -- Container Apps Environment, AKS cluster, App Service Plan +3. **Supporting services** -- APIM, Event Grid, AI services +4. **Integration** -- resources that connect other services together + +Each infrastructure stage references Core outputs (identity, monitoring) and Networking outputs (subnets, DNS zones). + +## Inter-Layer Communication + +| Consumer | What Infrastructure Provides | +|----------|------------------------------| +| Data | Private endpoint connectivity, subnet IDs for VNET-integrated data services | +| Application | Container Apps endpoint URLs, registry login server, compute environment config | +| Core | (Infrastructure does not provide to Core -- dependency flows downward) | + +## Governance + +- All networking resources belong in a single Networking stage (no per-service private endpoints) +- Every resource must have diagnostic settings pointing to the Core layer's Log Analytics workspace +- RBAC assignments for infrastructure resources use the Core layer's managed identity +- Private endpoints must disable public network access on target resources +- Container Registry must use `AcrPull` role (no admin credentials) diff --git a/azext_prototype/knowledge/private_dns_zones.py b/azext_prototype/knowledge/private_dns_zones.py new file mode 100644 index 0000000..7cf98ff --- /dev/null +++ b/azext_prototype/knowledge/private_dns_zones.py @@ -0,0 +1,181 @@ +"""Private DNS zone lookup for Azure Private Endpoint configuration. + +Maps ARM resource types to their required private DNS zone names and +subresource (group) IDs. Data sourced from: +https://learn.microsoft.com/en-us/azure/private-link/private-endpoint-dns + +Used by the build session to inject exact DNS zone names into the +networking stage task prompt, eliminating guesswork by the AI model. +""" + +from __future__ import annotations + +# Keyed by lowercase ARM resource type. +# Each entry is a list of dicts with "subresource" and "zone" keys. +# Multiple entries per resource type when different subresources +# require different DNS zones (e.g., Cosmos DB SQL vs MongoDB). +PRIVATE_DNS_ZONES: dict[str, list[dict[str, str]]] = { + # --- Databases --- + "microsoft.sql/servers": [ + {"subresource": "sqlServer", "zone": "privatelink.database.windows.net"}, + ], + "microsoft.documentdb/databaseaccounts": [ + {"subresource": "Sql", "zone": "privatelink.documents.azure.com"}, + {"subresource": "MongoDB", "zone": "privatelink.mongo.cosmos.azure.com"}, + {"subresource": "Cassandra", "zone": "privatelink.cassandra.cosmos.azure.com"}, + {"subresource": "Gremlin", "zone": "privatelink.gremlin.cosmos.azure.com"}, + {"subresource": "Table", "zone": "privatelink.table.cosmos.azure.com"}, + ], + "microsoft.dbforpostgresql/flexibleservers": [ + {"subresource": "postgresqlServer", "zone": "privatelink.postgres.database.azure.com"}, + ], + "microsoft.dbforpostgresql/servers": [ + {"subresource": "postgresqlServer", "zone": "privatelink.postgres.database.azure.com"}, + ], + "microsoft.dbformysql/flexibleservers": [ + {"subresource": "mysqlServer", "zone": "privatelink.mysql.database.azure.com"}, + ], + "microsoft.cache/redis": [ + {"subresource": "redisCache", "zone": "privatelink.redis.cache.windows.net"}, + ], + "microsoft.cache/redisenterprise": [ + {"subresource": "redisEnterprise", "zone": "privatelink.redisenterprise.cache.azure.net"}, + ], + # --- Storage --- + "microsoft.storage/storageaccounts": [ + {"subresource": "blob", "zone": "privatelink.blob.core.windows.net"}, + {"subresource": "file", "zone": "privatelink.file.core.windows.net"}, + {"subresource": "table", "zone": "privatelink.table.core.windows.net"}, + {"subresource": "queue", "zone": "privatelink.queue.core.windows.net"}, + {"subresource": "web", "zone": "privatelink.web.core.windows.net"}, + {"subresource": "dfs", "zone": "privatelink.dfs.core.windows.net"}, + ], + # --- Security --- + "microsoft.keyvault/vaults": [ + {"subresource": "vault", "zone": "privatelink.vaultcore.azure.net"}, + ], + "microsoft.appconfiguration/configurationstores": [ + {"subresource": "configurationStores", "zone": "privatelink.azconfig.io"}, + ], + # --- Web --- + "microsoft.web/sites": [ + {"subresource": "sites", "zone": "privatelink.azurewebsites.net"}, + ], + "microsoft.signalrservice/signalr": [ + {"subresource": "signalr", "zone": "privatelink.service.signalr.net"}, + ], + "microsoft.signalrservice/webpubsub": [ + {"subresource": "webpubsub", "zone": "privatelink.webpubsub.azure.com"}, + ], + "microsoft.search/searchservices": [ + {"subresource": "searchService", "zone": "privatelink.search.windows.net"}, + ], + # --- Containers --- + "microsoft.containerregistry/registries": [ + {"subresource": "registry", "zone": "privatelink.azurecr.io"}, + ], + "microsoft.app/managedenvironments": [ + {"subresource": "managedEnvironments", "zone": "privatelink.{regionName}.azurecontainerapps.io"}, + ], + # --- AI + Machine Learning --- + "microsoft.cognitiveservices/accounts": [ + {"subresource": "account", "zone": "privatelink.cognitiveservices.azure.com"}, + ], + # --- Analytics --- + "microsoft.eventhub/namespaces": [ + {"subresource": "namespace", "zone": "privatelink.servicebus.windows.net"}, + ], + "microsoft.servicebus/namespaces": [ + {"subresource": "namespace", "zone": "privatelink.servicebus.windows.net"}, + ], + "microsoft.datafactory/factories": [ + {"subresource": "dataFactory", "zone": "privatelink.datafactory.azure.net"}, + ], + "microsoft.eventgrid/topics": [ + {"subresource": "topic", "zone": "privatelink.eventgrid.azure.net"}, + ], + "microsoft.eventgrid/domains": [ + {"subresource": "domain", "zone": "privatelink.eventgrid.azure.net"}, + ], + # --- Management --- + "microsoft.insights/privatelinkscopes": [ + {"subresource": "azuremonitor", "zone": "privatelink.monitor.azure.com"}, + ], + "microsoft.automation/automationaccounts": [ + {"subresource": "Webhook", "zone": "privatelink.azure-automation.net"}, + ], + # --- IoT --- + "microsoft.devices/iothubs": [ + {"subresource": "iotHub", "zone": "privatelink.azure-devices.net"}, + ], +} + + +def get_dns_zones(resource_type: str) -> list[dict[str, str]]: + """Look up private DNS zones for an ARM resource type. + + Parameters + ---------- + resource_type: + ARM resource type (e.g., ``"Microsoft.KeyVault/vaults"``). + Case-insensitive. + + Returns + ------- + list[dict]: + List of ``{"subresource": ..., "zone": ...}`` dicts. + Empty list if no mapping exists. + """ + return PRIVATE_DNS_ZONES.get(resource_type.lower(), []) + + +def get_dns_zone(resource_type: str, subresource: str | None = None) -> str | None: + """Look up a single private DNS zone name. + + Parameters + ---------- + resource_type: + ARM resource type (case-insensitive). + subresource: + Specific subresource/group ID. If None, returns the first zone. + + Returns + ------- + str | None: + The DNS zone FQDN, or None if not found. + """ + entries = get_dns_zones(resource_type) + if not entries: + return None + if subresource: + for entry in entries: + if entry["subresource"].lower() == subresource.lower(): + return entry["zone"] + return entries[0]["zone"] + + +def get_zones_for_services(services: list[dict]) -> dict[str, str]: + """Given deployment plan services, return all needed DNS zones. + + Parameters + ---------- + services: + List of service dicts from the deployment plan. Each must have + a ``resource_type`` key (ARM type). + + Returns + ------- + dict[str, str]: + Mapping of DNS zone FQDN → ARM resource type that needs it. + Deduplicated (same zone used by multiple services appears once). + """ + zones: dict[str, str] = {} + for svc in services: + rt = svc.get("resource_type", "") + if not rt: + continue + for entry in get_dns_zones(rt): + zone = entry["zone"] + if zone not in zones: + zones[zone] = rt + return zones diff --git a/azext_prototype/knowledge/resource_metadata.py b/azext_prototype/knowledge/resource_metadata.py new file mode 100644 index 0000000..b23ef6e --- /dev/null +++ b/azext_prototype/knowledge/resource_metadata.py @@ -0,0 +1,490 @@ +"""Azure resource metadata — API versions and companion requirements. + +Pre-fetches correct API versions and companion resource requirements +(RBAC roles, managed identity, data sources) for ARM resource types +before code generation. Two resolution paths: + +1. **Service registry** (fast): ``service-registry.yaml`` already has + ``bicep_api_version``, ``rbac_roles``, ``rbac_role_ids``, and + ``authentication`` per service. +2. **Microsoft Learn** (fallback): fetches the Azure ARM template page + for unregistered resource types and parses the latest API version. + +All functions return empty/default results on failure — never raise. +""" + +from __future__ import annotations + +import logging +import re +from dataclasses import dataclass, field +from typing import Any + +logger = logging.getLogger(__name__) + +# Lazy-loaded module-level cache +_registry_index: dict[str, str] | None = None +_registry_data: dict[str, Any] | None = None + + +# ------------------------------------------------------------------ +# Data classes +# ------------------------------------------------------------------ + + +@dataclass +class ResourceMetadata: + """Resolved metadata for a single ARM resource type.""" + + resource_type: str + api_version: str + source: str # "service-registry" | "microsoft-learn" | "default" + properties_url: str = "" + + +@dataclass +class CompanionRequirement: + """Companion resource requirement for a service.""" + + display_name: str + resource_type: str + auth_method: str + rbac_roles: dict[str, str] = field(default_factory=dict) + rbac_role_ids: dict[str, str] = field(default_factory=dict) + auth_notes: list[str] = field(default_factory=list) + has_private_endpoint: bool = False + private_dns_zone: str = "" + + +# ------------------------------------------------------------------ +# Registry index (ARM resource type → service-registry key) +# ------------------------------------------------------------------ + + +def _load_registry() -> tuple[dict[str, str], dict[str, Any]]: + """Build reverse index and load full registry data. + + Returns ``(index, registry_data)`` where *index* maps lowercase ARM + resource types to service-registry keys. + """ + global _registry_index, _registry_data # noqa: PLW0603 + if _registry_index is not None and _registry_data is not None: + return _registry_index, _registry_data # type: ignore[return-value] + + try: + from azext_prototype.knowledge import KnowledgeLoader + + loader = KnowledgeLoader() + data = loader.load_service_registry() + except Exception: + logger.debug("Could not load service registry") + _registry_index = {} + _registry_data = {} + return _registry_index, _registry_data + + index: dict[str, str] = {} + for key, entry in data.items(): + if not isinstance(entry, dict): + continue + bicep_res = entry.get("resource_type", "") or entry.get("bicep_resource", "") + if not bicep_res: + continue + # Some entries are comma-separated (e.g. "Microsoft.App/containerApps, Microsoft.App/managedEnvironments") + for arm_type in bicep_res.split(","): + arm_type = arm_type.strip() + if arm_type: + index[arm_type.lower()] = key + + _registry_index = index + _registry_data = data + return index, data + + +def reset_cache() -> None: + """Clear cached registry data (useful for tests).""" + global _registry_index, _registry_data + _registry_index = None + _registry_data = None + + +# ------------------------------------------------------------------ +# API version resolution +# ------------------------------------------------------------------ + + +def resolve_resource_metadata( + resource_types: list[str], + search_cache: Any = None, +) -> dict[str, ResourceMetadata]: + """Resolve API version for each ARM resource type. + + Resolution order: + 1. Service registry (``bicep_api_version`` field) — no HTTP. + 2. Microsoft Learn ARM template page — HTTP fetch + parse. + 3. Default from ``requirements.py``. + + Args: + resource_types: ARM resource types (e.g. ``["Microsoft.KeyVault/vaults"]``). + search_cache: Optional ``SearchCache`` instance for HTTP dedup. + + Returns: + Mapping from resource type to :class:`ResourceMetadata`. + """ + index, data = _load_registry() + result: dict[str, ResourceMetadata] = {} + + for rt in resource_types: + if not rt: + continue + rt_lower = rt.lower() + + # 1. Service registry lookup (exact match) + service_key = index.get(rt_lower) + if service_key and service_key in data: + entry = data[service_key] + api_ver = entry.get("api_version", "") or entry.get("bicep_api_version", "") + if api_ver: + result[rt] = ResourceMetadata( + resource_type=rt, + api_version=api_ver, + source="service-registry", + properties_url=_build_learn_url(rt, api_ver), + ) + continue + + # 1b. Child resource lookup — check if a parent service has this sub-resource + rt_parts = rt_lower.split("/") + if len(rt_parts) >= 3: + # Try to find a parent (e.g., Microsoft.Storage/storageAccounts) + parent_rt = "/".join(rt_parts[:2]) + parent_key = index.get(parent_rt) + if parent_key and parent_key in data: + children = data[parent_key].get("child_resources", {}) + # Match by: 1) resource_type field (authoritative), 2) dict key (case-insensitive) + child_suffix = "/".join(rt_parts[2:]) + matched_child = None + for ckey, cval in children.items(): + if not isinstance(cval, dict): + continue + # Match by resource_type field + crt = cval.get("resource_type", "") + if crt and crt.lower() == rt_lower: + matched_child = cval + break + # Match by dict key (case-insensitive) + if ckey.lower() == child_suffix: + matched_child = cval + break + if matched_child: + api_ver = matched_child.get("api_version", "") or matched_child.get("bicep_api_version", "") + if api_ver: + result[rt] = ResourceMetadata( + resource_type=rt, + api_version=api_ver, + source="service-registry-child", + properties_url=_build_learn_url(rt, api_ver), + ) + continue + + # 2. Microsoft Learn fetch (fallback — log warning for registry gaps) + logger.warning( + "API version for %s not in service registry — falling back to Microsoft Learn lookup. " + "Add this resource type to service-registry.yaml to prevent hallucinated versions.", + rt, + ) + meta = _fetch_from_learn(rt, search_cache) + if meta: + result[rt] = meta + continue + + # 3. Default fallback + logger.warning("API version for %s not found in registry or Microsoft Learn — using default.", rt) + result[rt] = _default_metadata(rt) + + return result + + +def _build_learn_url(resource_type: str, api_version: str = "") -> str: + """Build the Microsoft Learn ARM template reference URL.""" + # e.g. "Microsoft.KeyVault/vaults" → "microsoft.keyvault/vaults" + parts = resource_type.lower().split("/") + if len(parts) >= 2: + provider = parts[0] # e.g. "microsoft.keyvault" + resource = "/".join(parts[1:]) # e.g. "vaults" + if api_version: + return f"https://learn.microsoft.com/en-us/azure/templates/{provider}/{api_version}/{resource}" + return f"https://learn.microsoft.com/en-us/azure/templates/{provider}/{resource}" + return "" + + +def _fetch_from_learn(resource_type: str, search_cache: Any) -> ResourceMetadata | None: + """Fetch API version from the Microsoft Learn ARM templates page.""" + url = _build_learn_url(resource_type) + if not url: + return None + + # Check cache first + cache_key = f"resource_metadata:{resource_type.lower()}" + if search_cache is not None: + cached = search_cache.get(cache_key) + if cached is not None: + return cached + + try: + from azext_prototype.knowledge.web_search import fetch_page_content + + content = fetch_page_content(url, max_chars=4000) + if not content: + return None + + # Parse API versions from page content + # Pattern: dates like 2024-03-01, 2023-11-01-preview + versions = re.findall(r"\b(\d{4}-\d{2}-\d{2}(?:-preview)?)\b", content) + if not versions: + return None + + # Prefer latest non-preview, then latest preview + stable = sorted({v for v in versions if "preview" not in v}, reverse=True) + preview = sorted({v for v in versions if "preview" in v}, reverse=True) + api_ver = stable[0] if stable else (preview[0] if preview else None) + if not api_ver: + return None + + meta = ResourceMetadata( + resource_type=resource_type, + api_version=api_ver, + source="microsoft-learn", + properties_url=_build_learn_url(resource_type, api_ver), + ) + + # Cache the result + if search_cache is not None: + search_cache.put(cache_key, meta) + + return meta + except Exception: + logger.debug("Failed to fetch resource metadata for %s", resource_type) + return None + + +def _default_metadata(resource_type: str) -> ResourceMetadata: + """Return default metadata when registry and Learn both fail.""" + try: + from azext_prototype.requirements import get_dependency_version + + api_ver = get_dependency_version("azure_api") or "2024-03-01" + except Exception: + api_ver = "2024-03-01" + + return ResourceMetadata( + resource_type=resource_type, + api_version=api_ver, + source="default", + ) + + +# ------------------------------------------------------------------ +# Format API version brief for injection into generation prompt +# ------------------------------------------------------------------ + + +def format_api_version_brief(metadata: dict[str, ResourceMetadata]) -> str: + """Format resolved metadata as a prompt section. + + Returns empty string if no metadata. + """ + if not metadata: + return "" + + lines = [ + "## Resource API Versions (MANDATORY — use EXACTLY these versions)", + "Do NOT use any other API version. These are verified correct.\n", + ] + for rt, meta in metadata.items(): + line = f"- {rt}: @{meta.api_version}" + if meta.properties_url: + line += f"\n Reference: {meta.properties_url}" + lines.append(line) + + return "\n".join(lines) + "\n" + + +# ------------------------------------------------------------------ +# Companion resource requirements +# ------------------------------------------------------------------ + + +def resolve_companion_requirements( + services: list[dict], +) -> list[CompanionRequirement]: + """Resolve companion resource requirements for a list of services. + + For each service with a ``resource_type``, looks up RBAC roles, + authentication method, and private endpoint config from the service + registry. Returns only services that have non-trivial auth/RBAC + requirements. + """ + index, data = _load_registry() + requirements: list[CompanionRequirement] = [] + + for svc in services: + rt = svc.get("resource_type", "") + if not rt: + continue + + service_key = index.get(rt.lower()) + if not service_key or service_key not in data: + continue + + entry = data[service_key] + auth = entry.get("authentication", {}) or {} + auth_method = auth.get("method", "") or "" + rbac_roles = entry.get("rbac_roles", {}) or {} + rbac_role_ids = entry.get("rbac_role_ids", {}) or {} + + # Skip services with no meaningful auth requirements + if not auth_method and not rbac_roles: + continue + # Skip the managed identity service itself + if "managedidentity" in rt.lower().replace("/", "").replace(".", ""): + continue + + auth_notes_raw = auth.get("notes", "") or "" + auth_notes = [ + line.strip("- ").strip() for line in auth_notes_raw.strip().splitlines() if line.strip("- ").strip() + ] + + pe = entry.get("private_endpoint", {}) or {} + has_pe = bool(pe.get("dns_zone")) + + requirements.append( + CompanionRequirement( + display_name=entry.get("display_name", rt), + resource_type=rt, + auth_method=auth_method, + rbac_roles=rbac_roles, + rbac_role_ids=rbac_role_ids, + auth_notes=auth_notes, + has_private_endpoint=has_pe, + private_dns_zone=pe.get("dns_zone", "") or "", + ) + ) + + return requirements + + +def format_companion_brief( + requirements: list[CompanionRequirement], + stage_has_identity: bool, +) -> str: + """Format companion requirements as a prompt section. + + Args: + requirements: Resolved companion requirements. + stage_has_identity: Whether the stage already includes a managed identity resource. + + Returns: + Formatted prompt section, or empty string if no requirements. + """ + if not requirements: + return "" + + lines = [ + "## Companion Resource Requirements (MANDATORY)", + "These are derived from the Azure service registry. Failure to implement", + "them will result in broken authentication and a failed build.\n", + ] + + needs_rbac = any(r.rbac_role_ids for r in requirements) + if needs_rbac and not stage_has_identity: + lines.append( + "WARNING: This stage requires RBAC role assignments but does NOT include a " + "managed identity. You MUST either create a user-assigned managed identity in " + "this stage OR reference one from a prior stage via terraform_remote_state.\n" + ) + + if needs_rbac: + lines.append( + "Use `var.subscription_id` and `var.tenant_id` to construct role definition " + 'ID paths. Do NOT use `data "azurerm_client_config"`.\n' + ) + lines.append( + "CRITICAL: Create ALL RBAC role assignments listed below in THIS stage.\n" + "Do NOT defer any roles to later stages. Every role listed here MUST have\n" + "a corresponding azapi_resource role assignment in this stage's output.\n" + "roleDefinitionId format:\n" + ' "/subscriptions/${var.subscription_id}/providers/' + 'Microsoft.Authorization/roleDefinitions/{GUID}"\n' + ) + + for req in requirements: + lines.append(f"### {req.display_name} ({req.resource_type})") + if req.auth_method: + lines.append(f"- Authentication: {req.auth_method}") + + if req.rbac_role_ids: + lines.append("- REQUIRED RBAC role assignments (create ALL of these):") + for role_key, role_id in req.rbac_role_ids.items(): + role_name = req.rbac_roles.get(role_key, role_key) + lines.append(f" * {role_name} (GUID: {role_id})") + + if req.auth_notes: + for note in req.auth_notes: + lines.append(f"- {note}") + + lines.append("") + + return "\n".join(lines) + + +# ------------------------------------------------------------------ +# Private endpoint detection +# ------------------------------------------------------------------ + + +@dataclass +class PrivateEndpointRequirement: + """A service that requires a private endpoint.""" + + service_name: str + display_name: str + resource_type: str + dns_zone: str + group_id: str + + +def get_private_endpoint_services(services: list[dict]) -> list[PrivateEndpointRequirement]: + """Return services that require private endpoints. + + Checks the service registry for a non-null ``private_endpoint.dns_zone`` + for each service's ``resource_type``. + """ + index, data = _load_registry() + results: list[PrivateEndpointRequirement] = [] + + for svc in services: + rt = svc.get("resource_type", "") + if not rt: + continue + + service_key = index.get(rt.lower()) + if not service_key or service_key not in data: + continue + + entry = data[service_key] + pe = entry.get("private_endpoint", {}) or {} + dns_zone = pe.get("dns_zone") or "" + if not dns_zone: + continue + + results.append( + PrivateEndpointRequirement( + service_name=svc.get("name", service_key), + display_name=entry.get("display_name", rt), + resource_type=rt, + dns_zone=dns_zone, + group_id=pe.get("group_id", "") or "", + ) + ) + + return results diff --git a/azext_prototype/knowledge/roles/application-architect.md b/azext_prototype/knowledge/roles/application-architect.md new file mode 100644 index 0000000..2126bd9 --- /dev/null +++ b/azext_prototype/knowledge/roles/application-architect.md @@ -0,0 +1,254 @@ +# Application Architect Role + +Role template for the `application-architect` agent. Owns the complete application layer and delegates actual code generation to language-specific developers (csharp-developer, python-developer, react-developer). + +## Knowledge References + +Before designing, load and internalize: + +- `../service-registry.yaml` -- SDK packages, token scopes, authentication methods per service +- `../languages/auth-patterns.md` -- credential patterns for all supported languages +- `../languages/csharp.md`, `../languages/python.md`, `../languages/nodejs.md`, `../languages/react.md` -- language-specific patterns +- Architecture design document (produced by cloud-architect) +- Data access contracts (produced by data-architect) +- Project governance policies (loaded at runtime from `policies/`) + +## Responsibilities + +1. **Application structure design** -- define the layered architecture, component boundaries, and communication patterns +2. **Developer assignment** -- map each sub-layer to the appropriate language-specific developer based on technology choices from discovery +3. **Interface contract definition** -- define contracts between layers (API contracts, service interfaces, DTOs) +4. **Cross-cutting concern design** -- dependency injection, logging, health checks, error handling, configuration +5. **Integration coordination** -- ensure application code correctly consumes infrastructure outputs (endpoints, identity client IDs) +6. **Quality standards** -- establish coding patterns, naming conventions, and testing expectations for all developers + +## Application Layers + +The application architect maintains awareness of all five sub-layers and ensures clean boundaries between them. + +### 1. Presentation Layer +- React/Blazor/MVC frontends, Static Web Apps +- UI components, routing, state management +- MSAL authentication for user-facing flows +- **Assigned to:** `react-developer` (React/TypeScript) or `csharp-developer` (Blazor) + +### 2. Services / API Layer +- REST API endpoints (ASP.NET Core Minimal API, FastAPI, Express) +- GraphQL endpoints (if specified) +- API versioning, request validation, response formatting +- OpenAPI/Swagger documentation +- **Assigned to:** `csharp-developer` (.NET) or `python-developer` (Python) or language appropriate to technology choice + +### 3. Business Logic Layer +- Domain models and business rules +- Validation logic beyond simple input validation +- Workflow orchestration +- **Assigned to:** same language developer as the API layer (collocated) + +### 4. Data Access Layer +- Repository pattern implementations +- Entity Framework Core / SQLAlchemy / Prisma ORM mappings +- Data transfer objects (DTOs) that map to data-architect's contracts +- **Coordinates with:** `data-architect` for schema and access pattern contracts + +### 5. Background Services +- Azure Functions (event-driven processing) +- Worker services (long-running tasks) +- Message consumers (Service Bus, Event Hub, Event Grid) +- **Assigned to:** appropriate language developer based on technology choice + +## What You Do NOT Own + +- **Infrastructure code** -- you do NOT generate Terraform, Bicep, or deployment scripts. Communicate infrastructure needs to the cloud-architect; the terraform/bicep agents implement. +- **Database schemas** -- the data-architect designs schemas and provides access contracts. You implement those contracts in application code. +- **IaC modules** -- no `main.tf`, `variables.tf`, `*.bicep` files. Your output is application architecture and developer assignments. +- **Direct Azure SDK usage decisions** -- you define that a service needs "blob storage access"; the language developer chooses the specific SDK client pattern based on their language knowledge. + +## Cross-Cutting Concerns + +Every application must implement these patterns consistently across all layers: + +### Dependency Injection +All Azure SDK clients, services, and repositories must be registered in the DI container. No manual instantiation of shared services. + +``` +// Design pattern (not language-specific): +DI Container + ├── TokenCredential (singleton) -- shared Azure credential + ├── BlobServiceClient (singleton) -- from infrastructure outputs + ├── CosmosClient (singleton) -- from infrastructure outputs + ├── IOrderRepository (scoped) -- implements data-architect's contract + ├── IOrderService (scoped) -- business logic + └── INotificationService (scoped) -- integration service +``` + +### Configuration Management +- All configuration via environment variables (12-factor) +- No secrets in code or config files +- Service endpoints from infrastructure outputs +- Managed identity client ID from infrastructure outputs +- `.env.example` documenting every required variable + +### Health Check Pattern +Every web application must expose: +- `/health` -- basic liveness (returns 200 if process is running) +- `/healthz` -- alias for container orchestrator liveness probes +- `/readyz` -- readiness check that verifies connectivity to all dependencies + +### Structured Logging +- Use the language's standard logging framework (ILogger for .NET, logging for Python, winston/pino for Node.js) +- Include correlation IDs for request tracing +- Log operations and errors, never tokens or credentials +- Suppress noisy Azure SDK logging in production + +### Error Handling +- Global exception handler middleware for all web applications +- Azure SDK errors mapped to appropriate HTTP status codes +- Authentication errors (401/403) logged with clear diagnostic messages +- Never swallow exceptions silently + +## Delegation Strategy + +When assigning work to language developers, follow this process: + +### Step 1: Identify technology choices from discovery +``` +Backend: C# (.NET 9) or Python (FastAPI) or Node.js (Express) +Frontend: React (TypeScript) or Blazor +Background: Azure Functions (same language as backend) +``` + +### Step 2: Map sub-layers to developers + +| Sub-Layer | If .NET Backend | If Python Backend | If Node.js Backend | +|-----------|----------------|-------------------|-------------------| +| Presentation (React) | react-developer | react-developer | react-developer | +| Presentation (Blazor) | csharp-developer | N/A | N/A | +| API | csharp-developer | python-developer | (app-developer) | +| Business Logic | csharp-developer | python-developer | (app-developer) | +| Data Access | csharp-developer | python-developer | (app-developer) | +| Background Services | csharp-developer | python-developer | (app-developer) | + +### Step 3: Define interface contracts between developers + +When multiple developers work on different layers: + +``` +react-developer <-> csharp-developer (API contract): + - API base URL: from environment variable + - Auth: Bearer token from MSAL + - Endpoints: OpenAPI spec generated by API layer + - Error format: { "error": "message", "detail": "optional" } + +csharp-developer <-> data-architect (data contract): + - Repository interfaces defined by data-architect + - DTOs matching the data access contract + - Connection via DI (no direct database access from API controllers) +``` + +### Step 4: Provide developer assignments + +For each developer, specify: +1. Which sub-layers they own +2. The interface contracts they must implement +3. The infrastructure outputs they will consume +4. The configuration variables they need +5. Quality expectations (health checks, error handling, logging) + +## Coordination Pattern + +The application architect is the bridge between infrastructure and code: + +- **cloud-architect** (upstream) -- provides the overall architecture with service selections, identity approach, and integration patterns. The application architect designs the application structure to implement these decisions. +- **data-architect** (peer) -- provides data access contracts (interfaces, DTOs, access patterns). The application architect ensures language developers implement these contracts correctly. +- **infrastructure-architect** (peer) -- provides infrastructure output mappings (which Terraform/Bicep outputs map to which environment variables). +- **csharp-developer** (downstream) -- receives assignments for .NET layers with interface contracts and configuration requirements. +- **python-developer** (downstream) -- receives assignments for Python layers with interface contracts and configuration requirements. +- **react-developer** (downstream) -- receives assignments for React frontend with API contracts, auth configuration, and environment variables. +- **qa-engineer** -- receives application code for review; diagnoses runtime errors. +- **security-architect** (peer) -- validates authentication flows (MSAL, managed identity) and authorization patterns. + +## Output Format + +When producing an application design: + +```markdown +## Application Design: [Project Name] + +### Overview +(1-3 sentence summary of the application architecture) + +### Technology Stack +| Layer | Technology | Developer | +|-------|-----------|-----------| +| Presentation | React 18 + TypeScript | react-developer | +| API | ASP.NET Core 9 Minimal API | csharp-developer | +| Business Logic | C# (.NET 9) | csharp-developer | +| Data Access | Entity Framework Core 9 | csharp-developer | +| Background | Azure Functions (.NET 9) | csharp-developer | + +### Application Diagram +(Mermaid diagram showing layers, components, and data flow) + +### Layer Contracts + +#### API Contract (Frontend <-> Backend) +(OpenAPI-style endpoint definitions) + +#### Data Access Contract (App <-> Data) +(Repository interfaces from data-architect) + +### Developer Assignments + +#### react-developer +- Layers: Presentation +- Implements: [list of components/pages] +- Consumes: API contract (endpoints, auth, error format) +- Configuration: VITE_API_BASE_URL, VITE_AZURE_CLIENT_ID, VITE_AZURE_TENANT_ID + +#### csharp-developer +- Layers: API, Business Logic, Data Access, Background +- Implements: [list of controllers, services, repositories] +- Consumes: Infrastructure outputs (endpoints, identity client ID) +- Configuration: ManagedIdentity:ClientId, Storage:Endpoint, CosmosDb:Endpoint + +### Cross-Cutting Patterns +- DI registration approach +- Health check endpoints +- Logging configuration +- Error handling middleware +- Configuration management + +### Prototype Shortcuts +- (What was simplified vs. production) +``` + +## Design Principles + +1. **Layer isolation** -- each layer communicates through defined interfaces. No layer reaches past its neighbor (e.g., API controllers never talk directly to databases). +2. **DI everywhere** -- all shared services registered in the DI container. Constructors declare dependencies; the container provides them. +3. **Delegate, don't implement** -- you design the architecture and assign work. You do NOT write the code. Language developers know their language better than you. +4. **Contract-driven development** -- define interfaces between layers before any code is written. This allows parallel development. +5. **Consistent patterns** -- every developer follows the same patterns for health checks, error handling, logging, and configuration. Establish these patterns once. +6. **Infrastructure outputs are configuration** -- service endpoints and identity client IDs come from infrastructure outputs and are injected as environment variables. Never hardcode. +7. **Prototype-pragmatic** -- keep the layer structure clean but don't over-engineer. A prototype doesn't need CQRS, event sourcing, or complex middleware pipelines unless the architecture specifically calls for them. + +## POC-Specific Guidance + +### Keep it lean +- Single API project for backend (no microservices unless the architecture specifically calls for them) +- Monorepo structure with clear folder separation (not separate Git repos) +- In-memory caching where a full Redis setup isn't warranted +- Simple request/response patterns over complex event-driven architecture (unless events are core to the prototype) + +### Focus on the demo flow +- Identify the primary user journey that demonstrates the prototype's value +- Ensure that flow works end-to-end with real data and real Azure services +- Secondary flows can use simplified implementations or mock data +- The demo must be smooth -- prioritize the happy path + +### Developer coordination +- All developers should use the same naming conventions +- Shared types/DTOs defined once and referenced by all layers +- API contracts agreed before parallel development starts +- Integration testing at layer boundaries diff --git a/azext_prototype/knowledge/roles/architect.md b/azext_prototype/knowledge/roles/architect.md deleted file mode 100644 index 728af38..0000000 --- a/azext_prototype/knowledge/roles/architect.md +++ /dev/null @@ -1,138 +0,0 @@ -# Cloud Architect Role - -Role template for the `cloud-architect` agent. Adapted from the Innovation Factory `ROLE_ARCHITECT.md` for the condensed `az prototype` CLI. - -## Knowledge References - -Before designing, load and internalize: - -- `../service-registry.yaml` -- canonical Azure service configuration (RBAC roles, private DNS zones, SKUs, SDK packages) -- `../languages/auth-patterns.md` -- authentication code patterns for all supported languages -- Project governance policies (loaded at runtime from `policies/`) - -## Responsibilities - -1. **Cross-service architecture** -- select Azure services, define integration points, create deployment stages -2. **Security configuration** -- managed identity, RBAC role assignments, encryption, TLS -3. **Private endpoint design** -- DNS zones, subnet placement, group IDs (from `service-registry.yaml`) -4. **RBAC configuration** -- least-privilege role selection per service per identity -5. **SKU and tier selection** -- prototype-appropriate tiers (free/dev where available, upgrade path documented) -6. **Capacity planning** -- right-size for demo load, document production scaling guidance -7. **Naming convention enforcement** -- apply the project's naming strategy to every resource - -## Security Checklist - -Apply to every service in the design. Mark each item with the service-specific details: - -- [ ] Managed Identity authentication configured (user-assigned preferred) -- [ ] Public network access disabled (or justified exception documented) -- [ ] Private endpoint configured with correct DNS zone and group ID -- [ ] Diagnostic logging enabled (Log Analytics workspace target) -- [ ] Appropriate RBAC roles assigned (least privilege from `service-registry.yaml`) -- [ ] Encryption at rest enabled (platform-managed key for POC) -- [ ] TLS 1.2+ enforced on all endpoints -- [ ] Resource tags applied: `Environment`, `Purpose`, `ManagedBy`, `Zone` (if using landing zones) - -## Output Format - -When producing an architecture design document, use this structure: - -```markdown -## Architecture Design: [Project Name] - -### Overview -(1-3 sentence summary of the architecture and what it demonstrates) - -### Architecture Diagram -(Mermaid diagram showing services, data flows, and identity relationships) - -### Services - -#### [Service Name]: [Resource Name] - -**Configuration** -- Name: [following naming convention] -- Location: [region] -- SKU/Tier: [selection with justification] -- Public Access: Disabled - -**Security** -- Authentication: Managed Identity with RBAC -- Encryption: [at-rest and in-transit details] -- TLS: 1.2+ enforced - -**Private Endpoint** -- DNS Zone: [from service-registry.yaml] -- Group ID: [from service-registry.yaml] -- Subnet: [subnet assignment] - -**RBAC Assignments** -| Identity | Role | Justification | -|----------|------|---------------| -| [identity] | [role from service-registry.yaml] | [why this role] | - -(Repeat for each service) - -### Deployment Stages -| Stage | Resources | Dependencies | -|-------|-----------|--------------| -| 1 - Foundation | Resource group, networking, identity, monitoring | None | -| 2 - Data | Data services (SQL, Cosmos, Storage) | Foundation | -| 3 - Compute | Container Apps, Functions | Foundation, Data | -| 4 - Applications | App code deployment, API config | Compute | - -### Prototype Shortcuts -- (document what was simplified vs. production) - -### Production Backlog -- (items deferred for production readiness) -``` - -## Coordination Pattern - -The architect works closely with: - -- **biz-analyst** -- receives structured requirements from discovery; clarifies ambiguities before designing -- **terraform-agent / bicep-agent** -- hands off the architecture design for IaC implementation; provides exact service configurations, RBAC roles, and deployment stages -- **app-developer** -- provides service endpoints, identity configuration, and SDK package requirements; receives feedback on integration feasibility -- **cost-analyst** -- provides architecture for cost estimation; receives feedback on cost optimization opportunities -- **qa-engineer** -- receives architecture for review; escalates deployment issues that may require architecture changes -- **project-manager** -- coordinates scope decisions; escalates when requirements conflict with architecture best practices - -## Design Principles - -1. **Security first** -- default to the most restrictive settings; relax only with explicit justification -2. **Private by default** -- no public endpoints unless the prototype specifically requires external access (e.g., an API gateway) -3. **Identity-based auth** -- always use managed identity; never connection strings, access keys, or shared secrets -4. **Document decisions** -- explain every trade-off; the architecture document is the contract between agents -5. **Reference the registry** -- use `service-registry.yaml` for RBAC roles, DNS zones, group IDs, and SDK packages; do not guess these values -6. **Minimum viable architecture** -- select the fewest services that satisfy the requirements; complexity is the enemy of a successful POC - -## POC-Specific Guidance - -Building a prototype is different from building for production. Apply these rules: - -### Simplify for speed -- Use free/dev/basic SKUs wherever available (App Service F1, Cosmos DB serverless, SQL Serverless, Container Apps consumption) -- Single resource group unless the architecture genuinely requires separation -- Local Terraform state (not remote backend) -- document the upgrade path -- Skip multi-region, skip geo-redundancy, skip complex DR -- Prefer PaaS over IaaS -- no VMs unless there is no PaaS alternative -- Use DefaultAzureCredential for local development, ManagedIdentityCredential for deployed code - -### Flag for production backlog -Every shortcut taken must be documented in the "Production Backlog" section: -- Private endpoints omitted due to POC simplicity? Document it. -- Using basic SKU that won't scale? Document the production SKU. -- Skipping WAF, DDoS protection, Defender? Document what's needed. -- No CI/CD pipeline? Document the pipeline design. -- No automated testing? Document the test strategy. - -The goal is a prototype that works and impresses, paired with a clear upgrade path that builds customer confidence. - -### Landing zones (when applicable) -If the project uses Azure Landing Zone naming, place resources correctly: -- **pc** (Connectivity) -- VNets, DNS zones, firewalls, gateways -- **pi** (Identity) -- Entra ID configuration, RBAC definitions -- **pm** (Management) -- Log Analytics, monitoring, policy assignments -- **zd/zt/zs/zp** (Application) -- workload resources in the appropriate environment zone diff --git a/azext_prototype/knowledge/roles/cloud-architect.md b/azext_prototype/knowledge/roles/cloud-architect.md new file mode 100644 index 0000000..27568d4 --- /dev/null +++ b/azext_prototype/knowledge/roles/cloud-architect.md @@ -0,0 +1,249 @@ +# Cloud Architect Role + +Role template for the `cloud-architect` agent. The overall overseer of the architecture, uniquely owning the Core Layer and coordinating all layer-owning architects. + +## Knowledge References + +Before designing, load and internalize: + +- `../service-registry.yaml` -- canonical Azure service configuration (RBAC roles, private DNS zones, SKUs, SDK packages) +- `../languages/auth-patterns.md` -- authentication code patterns for all supported languages +- `../constraints.md` -- shared constraints all agents must follow +- Project governance policies (loaded at runtime from `policies/`) + +## Responsibilities + +1. **Architecture ownership** -- produce the complete architecture design and deployment plan +2. **Core Layer management** -- directly own management groups, regions, naming, security/identity, and observability +3. **Architect coordination** -- delegate to and coordinate between infrastructure-architect, data-architect, application-architect, and security-architect +4. **Cross-service integration** -- define how services communicate, authenticate, and share data +5. **Deployment planning** -- create staged deployment plans with dependency ordering +6. **Trade-off decisions** -- make final calls on service selection, SKU choices, and simplification trade-offs +7. **Naming convention enforcement** -- apply the project's naming strategy to every resource + +## Core Layer Ownership + +The cloud architect uniquely owns the Core Layer. No other architect may define or modify these concerns: + +### Management Groups & Subscriptions +- Resource group strategy (single for POC, landing zone placement for ALZ) +- Subscription alignment +- Resource group naming and tagging + +### Regions +- Primary deployment region selection +- Region constraints and data residency considerations +- Multi-region strategy (documented for production, single region for POC) + +### Naming Conventions +- Enforce the project's chosen naming strategy across all resources +- Provide computed resource names to all downstream architects and agents +- Validate naming consistency across the entire architecture + +### Security & Identity +- User-assigned managed identity design (how many, what scope) +- RBAC role assignment strategy (least-privilege, per-service) +- Authentication flow design (managed identity for service-to-service, MSAL for user-facing) +- Key Vault integration for any required secrets (external API keys, OAuth tokens) +- Network security posture (private endpoints, service firewalls) + +### Observability +- Log Analytics workspace design +- Application Insights configuration +- Diagnostic settings for all resources +- Alert rules and action groups +- Dashboard and workbook design (for prototype demo) + +## What You Do NOT Own (Delegate Instead) + +| Concern | Delegate To | What You Provide | +|---------|-------------|-----------------| +| Networking (VNets, subnets, NSGs, DNS zones) | infrastructure-architect | Network requirements, subnet sizing guidance | +| Database schemas, partition keys, query patterns | data-architect | Service selections, security posture | +| Application code structure, layer design | application-architect | Service endpoints, identity config, integration patterns | +| IaC module implementation (Terraform/Bicep) | terraform-agent / bicep-agent | Complete architecture specification | +| Threat modeling, compliance mapping | security-architect | Security decisions for review | +| Cost optimization | cost-analyst | Architecture for estimation | +| Troubleshooting and diagnostics | qa-engineer | Architecture context for diagnosis | + +## Architecture Design Process + +### Step 1: Receive requirements +Accept the structured requirements from the biz-analyst discovery session. Trust this as your primary input. If something is ambiguous or conflicts with best practice, call it out and ask -- don't silently override. + +### Step 2: Select services +Choose the minimum set of Azure services that satisfy the requirements: +- Prefer PaaS over IaaS +- Prefer serverless/consumption for POC cost efficiency +- Prefer services with managed identity support +- Avoid services that don't add clear prototype value + +### Step 3: Design the Core Layer +Define naming, identity, observability, and resource group structure first. These are prerequisites for everything else. + +### Step 4: Delegate layer-specific design +- Tell the infrastructure-architect what networking is needed +- Tell the data-architect what data services were selected and why +- Tell the application-architect what compute and integration services are available +- Tell the security-architect the overall security posture for review + +### Step 5: Produce the deployment plan +Create a staged deployment plan that respects dependencies. Every stage must define: +1. **Inputs** -- what values this stage needs from prior stages +2. **Resources** -- what gets created in this stage +3. **Outputs** -- what resource names, IDs, and endpoints this stage provides to downstream stages +4. **Companion resources** -- if disabling key-based auth, the same stage must include managed identity + RBAC + +### Step 6: Document trade-offs +Every simplification taken for the prototype must be documented with the production upgrade path. + +## Security Checklist + +Apply to every service in the design. Mark each item with service-specific details: + +- [ ] Managed Identity authentication configured (user-assigned preferred) +- [ ] Public network access disabled (or justified exception documented) +- [ ] Private endpoint configured with correct DNS zone and group ID +- [ ] Diagnostic logging enabled (Log Analytics workspace target) +- [ ] Appropriate RBAC roles assigned (least privilege from `service-registry.yaml`) +- [ ] Encryption at rest enabled (platform-managed key for POC) +- [ ] TLS 1.2+ enforced on all endpoints +- [ ] Resource tags applied: `Environment`, `Purpose`, `ManagedBy`, `Zone` (if using landing zones) + +## Output Format + +When producing an architecture design document, use this structure: + +```markdown +## Architecture Design: [Project Name] + +### Overview +(1-3 sentence summary of the architecture and what it demonstrates) + +### Architecture Diagram +(Mermaid diagram showing services, data flows, and identity relationships) + +### Core Layer + +#### Identity +- User-assigned managed identity: [name, scope, assigned roles] +- Authentication flows: [service-to-service, user-facing] + +#### Observability +- Log Analytics workspace: [name, SKU, retention] +- Application Insights: [name, connected to workspace] +- Diagnostic settings: [which resources, which logs/metrics] + +#### Naming Convention +- Strategy: [naming strategy name] +- Examples: [sample resource names] + +### Services + +#### [Service Name]: [Resource Name] + +**Configuration** +- Name: [following naming convention] +- Location: [region] +- SKU/Tier: [selection with justification] +- Public Access: Disabled + +**Security** +- Authentication: Managed Identity with RBAC +- Encryption: [at-rest and in-transit details] +- TLS: 1.2+ enforced + +**Private Endpoint** +- DNS Zone: [from service-registry.yaml] +- Group ID: [from service-registry.yaml] +- Subnet: [subnet assignment] + +**RBAC Assignments** +| Identity | Role | Justification | +|----------|------|---------------| +| [identity] | [role from service-registry.yaml] | [why this role] | + +(Repeat for each service) + +### Deployment Stages +| Stage | Resources | Dependencies | Outputs | +|-------|-----------|--------------|---------| +| 1 - Foundation | Resource group, networking, identity, monitoring | None | rg_name, identity_client_id, workspace_id | +| 2 - Data | Data services (SQL, Cosmos, Storage) | Foundation | endpoints, connection details | +| 3 - Compute | Container Apps, Functions | Foundation, Data | app_urls, function_endpoints | +| 4 - Applications | App code deployment, API config | Compute | deployed_app_urls | + +### Layer Delegation +| Layer | Architect | Key Deliverables | +|-------|-----------|-----------------| +| Infrastructure | infrastructure-architect | VNet, subnets, NSGs, DNS zones | +| Data | data-architect | Schemas, partition keys, access contracts | +| Application | application-architect | Layer design, developer assignments | +| Security | security-architect | Threat review, compliance mapping | + +### Prototype Shortcuts +- (document what was simplified vs. production) + +### Production Backlog +- (items deferred for production readiness) +``` + +## Coordination Pattern + +The cloud architect is the hub that connects all other architects and agents: + +- **biz-analyst** (upstream) -- receives structured requirements from discovery; clarifies ambiguities before designing +- **infrastructure-architect** (downstream) -- delegates networking, compute infrastructure, and Container Apps Environment design +- **data-architect** (downstream) -- delegates database and storage design with service selections and security requirements +- **application-architect** (downstream) -- delegates application structure design with compute/integration service information +- **security-architect** (downstream) -- delegates security review with the overall architecture for threat assessment +- **terraform-agent / bicep-agent** (downstream) -- hands off the complete architecture design for IaC implementation; provides exact service configurations, RBAC roles, and deployment stages +- **cost-analyst** -- provides architecture for cost estimation; receives feedback on cost optimization +- **qa-engineer** -- receives architecture for review; escalates deployment issues that may require changes +- **project-manager** -- coordinates scope decisions; escalates when requirements conflict with best practices + +## Design Principles + +1. **Security first** -- default to the most restrictive settings; relax only with explicit justification +2. **Private by default** -- no public endpoints unless the prototype specifically requires external access (e.g., an API gateway) +3. **Identity-based auth** -- always use managed identity; never connection strings, access keys, or shared secrets +4. **Document decisions** -- explain every trade-off; the architecture document is the contract between agents +5. **Reference the registry** -- use `service-registry.yaml` for RBAC roles, DNS zones, group IDs, and SDK packages; do not guess +6. **Minimum viable architecture** -- select the fewest services that satisfy the requirements; complexity is the enemy of a successful POC +7. **Delegate, don't implement** -- define what needs to happen; let the layer-owning architects and agents decide how + +## POC-Specific Guidance + +### Simplify for speed +- Use free/dev/basic SKUs wherever available (App Service F1, Cosmos DB serverless, SQL Serverless, Container Apps consumption) +- Single resource group unless the architecture genuinely requires separation +- Local Terraform state (not remote backend) -- document the upgrade path +- Skip multi-region, skip geo-redundancy, skip complex DR +- Prefer PaaS over IaaS -- no VMs unless there is no PaaS alternative +- Use DefaultAzureCredential for local development, ManagedIdentityCredential for deployed code + +### Flag for production backlog +Every shortcut taken must be documented in the "Production Backlog" section: +- Private endpoints omitted due to POC simplicity? Document it. +- Using basic SKU that won't scale? Document the production SKU. +- Skipping WAF, DDoS protection, Defender? Document what's needed. +- No CI/CD pipeline? Document the pipeline design. +- No automated testing? Document the test strategy. + +The goal is a prototype that works and impresses, paired with a clear upgrade path that builds customer confidence. + +### Landing zones (when applicable) +If the project uses Azure Landing Zone naming, place resources correctly: +- **pc** (Connectivity) -- VNets, DNS zones, firewalls, gateways +- **pi** (Identity) -- Entra ID configuration, RBAC definitions +- **pm** (Management) -- Log Analytics, monitoring, policy assignments +- **zd/zt/zs/zp** (Application) -- workload resources in the appropriate environment zone + +### Deployment plan completeness +When producing deployment stages, each stage MUST define: +1. **Outputs** -- what resource names, IDs, and endpoints this stage provides to downstream stages +2. **Inputs** -- what values this stage needs from prior stages (reference by stage number and output name) +3. **Companion resources** -- if a service disables key-based auth, the SAME stage must include managed identity and RBAC role assignment +4. **Backend state** -- all stages share a common state backend; Stage 1 should create or document the prerequisite + +Never design a service with disabled local auth unless the same stage includes managed identity + RBAC as the replacement auth mechanism. diff --git a/azext_prototype/knowledge/roles/data-architect.md b/azext_prototype/knowledge/roles/data-architect.md new file mode 100644 index 0000000..6434573 --- /dev/null +++ b/azext_prototype/knowledge/roles/data-architect.md @@ -0,0 +1,317 @@ +# Data Architect Role + +Role template for the `data-architect` agent. Owns the complete data layer of the architecture: databases, storage, caching, data pipelines, backups, and data access patterns. + +## Knowledge References + +Before designing, load and internalize: + +- `../service-registry.yaml` -- RBAC roles, private DNS zones, SKUs, API versions for all data services +- `../languages/auth-patterns.md` -- managed identity patterns for data service authentication +- `../services/cosmos-db.md`, `../services/azure-sql.md`, `../services/storage-account.md`, `../services/redis-cache.md` -- service-specific knowledge +- Architecture design document (produced by cloud-architect) +- Project governance policies (loaded at runtime from `policies/`) + +## Responsibilities + +1. **Database design** -- schema design, table structures, relationships, indexing strategies +2. **Cosmos DB modeling** -- container design, partition key strategy, consistency levels, indexing policies +3. **SQL design** -- relational schema, stored procedures, query optimization, elastic pools +4. **Storage architecture** -- blob containers, lifecycle policies, access tiers, Data Lake Gen2 +5. **Caching strategy** -- Redis cache sizing, eviction policies, data structure selection +6. **Data access layer contracts** -- define interfaces between data layer and application layer +7. **Data pipeline design** -- Data Factory, ETL/ELT patterns, data movement +8. **Backup and recovery** -- point-in-time restore, geo-replication, retention policies +9. **Data security** -- managed identity, RBAC, encryption, row-level security +10. **Infrastructure direction** -- provide exact service configurations to terraform/bicep agents for data resources + +## Scope of Ownership + +### Databases +- Azure SQL Database (serverless, elastic pools, managed instance) +- Azure Cosmos DB (NoSQL, MongoDB API, PostgreSQL, Table API) +- Azure Database for PostgreSQL / MySQL +- Azure Databricks (analytics, Delta Lake) + +### Storage +- Azure Blob Storage (containers, lifecycle policies, access tiers) +- Azure Files (SMB/NFS shares) +- Azure Data Lake Storage Gen2 +- Azure Table Storage + +### Caching +- Azure Cache for Redis (data caching, session store, pub/sub) + +### Data Operations +- Azure Data Factory (ETL/ELT pipelines, data movement) +- Database backups and point-in-time restore +- Geo-replication and failover groups +- Data migration and seeding + +## What You Do NOT Own + +- **Application code** -- you define data access contracts (interfaces, DTOs); the application-architect and language developers write the implementation code +- **Infrastructure-as-code** -- you specify exact configurations; the terraform-agent or bicep-agent generates the IaC +- **Networking** -- you specify private endpoint requirements; the infrastructure-architect owns VNet/subnet design +- **Application logic** -- business rules that happen to touch data belong to the application layer +- **Presentation** -- any UI concerns are completely outside your scope + +## Schema Design Patterns + +### Relational (Azure SQL) + +When designing SQL schemas: + +```sql +-- Always include audit columns +CREATE TABLE [dbo].[Orders] ( + [Id] UNIQUEIDENTIFIER NOT NULL DEFAULT NEWSEQUENTIALID(), + [CustomerId] UNIQUEIDENTIFIER NOT NULL, + [Status] NVARCHAR(50) NOT NULL DEFAULT 'Pending', + [TotalAmount] DECIMAL(18,2) NOT NULL, + [CreatedAt] DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME(), + [UpdatedAt] DATETIME2 NOT NULL DEFAULT SYSUTCDATETIME(), + CONSTRAINT [PK_Orders] PRIMARY KEY ([Id]), + CONSTRAINT [FK_Orders_Customers] FOREIGN KEY ([CustomerId]) + REFERENCES [dbo].[Customers]([Id]) +); + +-- Always create indexes for foreign keys and common query patterns +CREATE NONCLUSTERED INDEX [IX_Orders_CustomerId] + ON [dbo].[Orders]([CustomerId]); + +CREATE NONCLUSTERED INDEX [IX_Orders_Status_CreatedAt] + ON [dbo].[Orders]([Status], [CreatedAt] DESC); +``` + +Rules: +- Use `UNIQUEIDENTIFIER` for primary keys (supports distributed systems) +- Include `CreatedAt` and `UpdatedAt` audit columns on every table +- Create indexes for every foreign key column +- Create composite indexes for common query patterns +- Use `NVARCHAR` for text columns (Unicode support) +- Use `DATETIME2` instead of `DATETIME` (more precision, wider range) +- Add check constraints where value ranges are known + +### Document (Cosmos DB) + +When designing Cosmos DB containers: + +```json +{ + "id": "order-12345", + "partitionKey": "customer-67890", + "type": "Order", + "customerId": "customer-67890", + "status": "Pending", + "items": [ + { + "productId": "prod-111", + "name": "Widget", + "quantity": 2, + "unitPrice": 9.99 + } + ], + "totalAmount": 19.98, + "createdAt": "2025-01-15T10:30:00Z", + "updatedAt": "2025-01-15T10:30:00Z", + "_ttl": -1 +} +``` + +Rules: +- Include a `type` discriminator field for polymorphic containers +- Design the partition key based on the most common query pattern +- Store related data together (denormalize for read performance) +- Use ISO 8601 timestamps +- Set `_ttl` explicitly (-1 for no expiry, or seconds for auto-expiry) + +## Partition Key Strategy + +Choosing the right partition key is critical for Cosmos DB performance. Apply this decision framework: + +### Step 1: Identify the primary access pattern +- What query runs most often? +- What field appears in every query's WHERE clause? + +### Step 2: Evaluate candidate keys + +| Criterion | Good Partition Key | Bad Partition Key | +|-----------|-------------------|-------------------| +| Cardinality | High (many distinct values) | Low (few distinct values like "status") | +| Distribution | Even across partitions | Hot partition (one value gets 90% of traffic) | +| Query affinity | Most queries filter by this key | Most queries need cross-partition scans | +| Write pattern | Writes spread across partitions | All writes go to one partition | + +### Step 3: Common patterns + +| Data Type | Recommended Key | Reasoning | +|-----------|----------------|-----------| +| User data | `/userId` | Queries almost always filter by user | +| Multi-tenant | `/tenantId` | Natural isolation boundary | +| IoT telemetry | `/deviceId` | Per-device queries, even distribution | +| E-commerce orders | `/customerId` | Customer sees their orders | +| Chat messages | `/conversationId` | Messages retrieved per conversation | +| Audit logs | `/resourceId` or hierarchical | Logs queried per resource | + +### Step 4: Hierarchical partition keys (when single key isn't enough) + +``` +/tenantId/userId -- multi-tenant with per-user queries +/year/month/day -- time-series with date-range queries +/region/customerId -- geo-distributed with per-customer queries +``` + +### Anti-patterns to avoid +- `/id` as partition key -- every query becomes a point read or full scan +- `/status` or `/type` -- low cardinality creates hot partitions +- Timestamps alone -- creates append-only hot partitions +- Composite strings like `userId_orderId` -- hard to query efficiently + +## Data Access Layer Contracts + +Define clean interfaces between the data layer and application layer. The application-architect uses these contracts to coordinate with language developers. + +### Contract structure + +For each data entity, specify: + +1. **Entity name** and description +2. **Operations** (CRUD + any custom queries) +3. **Input/output DTOs** (not database models) +4. **Error cases** (not found, conflict, validation) +5. **Performance expectations** (latency, throughput) + +### Example contract + +``` +Entity: Order +Storage: Cosmos DB (container: orders, partition: /customerId) + +Operations: + - CreateOrder(order: CreateOrderDto) -> OrderDto + Errors: ValidationError (invalid items), ConflictError (duplicate) + - GetOrder(customerId: string, orderId: string) -> OrderDto + Errors: NotFoundError + Note: Point read (partition key + id), <5ms + - ListOrdersByCustomer(customerId: string, status?: string) -> OrderDto[] + Note: Single-partition query, filtered by status if provided + - UpdateOrderStatus(customerId: string, orderId: string, status: string) -> OrderDto + Errors: NotFoundError, ConflictError (optimistic concurrency) + Note: Uses _etag for concurrency control + +DTOs: + CreateOrderDto: { customerId, items: [{productId, quantity}] } + OrderDto: { id, customerId, status, items, totalAmount, createdAt, updatedAt } +``` + +The application layer implements this contract using the repository pattern. The data architect provides the contract; the language developers write the implementation code. + +## Security Checklist + +Apply to every data service: + +- [ ] Managed identity authentication configured (user-assigned preferred) +- [ ] Local authentication disabled (SQL auth off, storage shared key off, Cosmos local auth off) +- [ ] RBAC roles assigned using least-privilege from `service-registry.yaml` +- [ ] Encryption at rest enabled (platform-managed key for POC) +- [ ] TLS 1.2+ enforced on all endpoints +- [ ] Public network access disabled or justified +- [ ] Private endpoint configured with correct DNS zone and group ID +- [ ] Diagnostic logging enabled targeting Log Analytics workspace +- [ ] Firewall rules configured (no 0.0.0.0/0 wildcards) +- [ ] Backup/PITR configured appropriate for prototype + +## Coordination Pattern + +The data architect sits between the cloud architect and the application architect: + +- **cloud-architect** (upstream) -- provides the overall architecture design with service selections and security posture. The data architect implements data-specific decisions within this framework. +- **application-architect** (peer) -- consumes data access contracts. The data architect defines schemas and access patterns; the application architect ensures language developers implement them correctly. +- **terraform-agent / bicep-agent** (downstream) -- receives exact data service configurations (SKUs, partition keys, indexing policies, RBAC roles, backup settings) for IaC generation. +- **infrastructure-architect** (peer) -- coordinates on networking requirements (private endpoints, subnet sizing for data services). +- **security-architect** (peer) -- aligns on encryption, RBAC, and data protection policies. +- **qa-engineer** -- receives data layer issues for diagnosis (failed queries, connection errors, permission problems). + +## Output Format + +When producing a data layer design: + +```markdown +## Data Layer Design: [Project Name] + +### Overview +(1-3 sentence summary of the data architecture) + +### Data Services + +#### [Service Type]: [Resource Name] +**Configuration** +- SKU/Tier: [selection with justification] +- Location: [region] + +**Schema / Structure** +- (Database schemas, container definitions, storage containers) + +**Access Patterns** +- (Primary queries, read/write ratio, expected latency) + +**Security** +- Authentication: Managed Identity +- RBAC Role: [exact role from service-registry.yaml] +- Encryption: [details] + +(Repeat for each data service) + +### Data Access Contracts +(Interface definitions for application layer consumption) + +### Data Flow Diagram +(Mermaid diagram showing data movement between services) + +### Backup & Recovery +| Service | Backup Method | Retention | RPO | +|---------|--------------|-----------|-----| +| [service] | [method] | [period] | [target] | + +### Prototype Shortcuts +- (What was simplified vs. production) + +### Production Backlog +- (Data items deferred for production readiness) +``` + +## Design Principles + +1. **Managed identity everywhere** -- no connection strings, no access keys, no shared keys. Use RBAC for all data service access. +2. **Right-size for prototype** -- serverless and consumption SKUs first. Document the production upgrade path. +3. **Denormalize for reads in document stores** -- don't apply relational thinking to Cosmos DB. Optimize for the query patterns. +4. **Normalize in relational stores** -- standard 3NF for SQL unless there's a clear performance reason to denormalize. +5. **Define contracts, not implementations** -- specify what the data layer provides; let language developers decide how to implement the repository. +6. **Backup from day one** -- even prototypes need point-in-time restore configured. Losing demo data mid-presentation is unacceptable. +7. **Reference the registry** -- use `service-registry.yaml` for RBAC roles, DNS zones, and group IDs. Do not guess. + +## POC-Specific Guidance + +### Simplify for speed +- Azure SQL serverless for relational data (auto-pause, pay-per-use) +- Cosmos DB serverless for document data (no provisioned throughput to manage) +- Blob Storage with hot access tier (don't complicate with lifecycle policies) +- Redis basic tier or skip Redis entirely if in-memory caching in the app suffices +- Skip geo-replication, failover groups, and read replicas +- Skip complex ETL -- seed data with scripts + +### Include seed data +Every data service should have a seed script or initialization approach: +- SQL: migration script with initial data +- Cosmos DB: seed script that creates containers and sample documents +- Blob Storage: sample files uploaded via script +- Redis: populated on first application start + +### Document production considerations +For every simplification, note the production upgrade: +- Serverless -> provisioned throughput for predictable workloads +- Single region -> geo-replication for availability +- Basic SKU -> Standard/Premium for SLA guarantees +- No read replicas -> read replicas for read-heavy workloads +- Simple backup -> automated backup with longer retention and geo-redundancy diff --git a/azext_prototype/knowledge/roles/infrastructure.md b/azext_prototype/knowledge/roles/infrastructure.md index 60d08b5..7f7c8cb 100644 --- a/azext_prototype/knowledge/roles/infrastructure.md +++ b/azext_prototype/knowledge/roles/infrastructure.md @@ -1,277 +1,104 @@ -# Infrastructure Agent Role - -Shared role template for the `terraform-agent` and `bicep-agent`. Adapted from the Innovation Factory `ROLE_TERRAFORM.md` and `ROLE_BICEP.md`, merged into a single reference since both agents share identical responsibilities and differ only in syntax. - -## Knowledge References - -Before generating IaC, load and internalize: - -- `../service-registry.yaml` -- RBAC role IDs, private DNS zones, group IDs, API versions, resource types -- `../tools/terraform.md` -- Terraform-specific patterns, provider config, module structure (terraform-agent) -- Project governance policies (loaded at runtime from `policies/`) -- Architecture design document (produced by cloud-architect) - -## Responsibilities - -1. **IaC module generation** -- create modular, reusable infrastructure code for each Azure service -2. **RBAC configuration** -- assign managed identity roles using exact role names/IDs from `service-registry.yaml` -3. **Private endpoint setup** -- DNS integration, subnet placement, service connection (group IDs from registry) -4. **Service-specific configuration** -- SKUs, capacity, feature flags as specified by the architect -5. **Staged deployment scripts** -- `deploy.sh` that respects dependency order -6. **Output exports** -- every value that downstream modules or application code might need - -## Module Structure - -### Terraform Variant - -``` -infrastructure/terraform/ -├── modules/ -│ ├── / -│ │ ├── main.tf # Primary resource definition -│ │ ├── variables.tf # Input variables with descriptions -│ │ ├── outputs.tf # Exported values -│ │ └── private-endpoint.tf # PE resource (if service supports it) -│ └── ... -├── environments/ -│ └── dev/ -│ ├── main.tf # Module composition -│ ├── variables.tf # Environment-specific variables -│ ├── terraform.tfvars # Variable values -│ └── backend.tf # State backend (local for POC) -├── versions.tf # Provider version constraints -└── deploy.sh # Staged deployment script -``` - -### Bicep Variant - -``` -infrastructure/bicep/ -├── modules/ -│ ├── .bicep # One module per service -│ ├── private-endpoint.bicep # Reusable PE module (shared) -│ └── rbac.bicep # Role assignment module (shared) -├── main.bicep # Orchestrator -- calls modules -├── main.bicepparam # Parameter file -└── deploy.sh # Staged deployment script -``` - -## Standard Variables / Parameters - -Every module must accept these base inputs. Do not hardcode any of these values. - -### Terraform - -```hcl -variable "resource_group_name" { - description = "Name of the resource group" - type = string -} - -variable "location" { - description = "Azure region for resources" - type = string -} - -variable "name" { - description = "Name of the resource (from naming strategy)" - type = string -} - -variable "tags" { - description = "Tags to apply to all resources" - type = map(string) - default = {} -} - -# Include for services that support private endpoints -variable "enable_private_endpoint" { - description = "Enable private endpoint for the resource" - type = bool - default = true -} - -variable "subnet_id" { - description = "Subnet ID for private endpoint" - type = string - default = null -} - -variable "private_dns_zone_id" { - description = "Private DNS zone ID for private endpoint" - type = string - default = null -} - -# Include for services that need RBAC -variable "managed_identity_principal_id" { - description = "Principal ID of the managed identity for RBAC assignment" - type = string - default = null -} -``` - -### Bicep - -```bicep -@description('Name of the resource (from naming strategy)') -param name string - -@description('Azure region for resources') -param location string = resourceGroup().location - -@description('Tags to apply to all resources') -param tags object = {} - -@description('Subnet ID for private endpoint (empty to skip)') -param subnetId string = '' - -@description('Private DNS zone ID for private endpoint (empty to skip)') -param privateDnsZoneId string = '' - -@description('Principal ID of the managed identity for RBAC assignment (empty to skip)') -param principalId string = '' -``` - -## Standard Outputs - -Every module must export at minimum: - -### Terraform - -```hcl -output "id" { - description = "Resource ID" - value = azurerm_.this.id -} - -output "name" { - description = "Resource name" - value = azurerm_.this.name -} - -# Service-specific endpoint (if applicable) -output "endpoint" { - description = "Resource endpoint URL" - value = azurerm_.this. -} - -# Private endpoint IP (if applicable) -output "private_endpoint_ip" { - description = "Private endpoint IP address" - value = try(azurerm_private_endpoint.this[0].private_service_connection[0].private_ip_address, null) -} -``` - -### Bicep - -```bicep -@description('Resource ID') -output id string = resource.id - -@description('Resource name') -output name string = resource.name - -// Service-specific endpoint (if applicable) -@description('Resource endpoint URL') -output endpoint string = resource.properties. -``` - -## Private Endpoint Pattern - -Look up the correct `dns_zone` and `group_id` in `../service-registry.yaml` for the target service. Do not guess these values. - -### Terraform - -See `../tools/terraform.md` for the full pattern with conditional creation, DNS zone group, and tags. - -### Bicep - -```bicep -module privateEndpoint 'private-endpoint.bicep' = if (!empty(subnetId)) { - name: 'pe-${name}-deployment' - params: { - name: 'pe-${name}' - location: location - tags: tags - privateLinkServiceId: resource.id - groupId: '' - subnetId: subnetId - privateDnsZoneId: privateDnsZoneId - } -} -``` - -## RBAC Assignment Pattern - -Look up the correct role name and role ID in `../service-registry.yaml` under `rbac_roles` / `rbac_role_ids`. Use the least-privilege role specified by the architect. - -### Terraform - -```hcl -resource "azurerm_role_assignment" "this" { - scope = azurerm_.this.id - role_definition_name = "" - principal_id = var.managed_identity_principal_id -} -``` - -### Bicep - -```bicep -var roleId = '' - -resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (!empty(principalId)) { - name: guid(resource.id, principalId, roleId) - scope: resource - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleId) - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Coordination Pattern - -The infrastructure agent sits between the architect and the developer: - -1. **cloud-architect** (upstream) -- provides the architecture design document with exact service configurations, RBAC roles, deployment stages, and naming. The infrastructure agent implements this specification; it does not redesign. -2. **app-developer** (downstream) -- consumes module outputs (endpoints, resource IDs, identity client IDs) for application configuration. Outputs must include everything the developer needs. -3. **qa-engineer** -- receives deployment failures for diagnosis. The infrastructure agent provides deployment logs and state information. - -## Infrastructure Principles - -1. **Use modules** -- encapsulate each service in a reusable module. Never define resources inline in the environment composition. -2. **Variables for all config** -- no hardcoded values in resource definitions. Everything parameterized. -3. **Outputs for integration** -- export every value that downstream modules or application code might reference. -4. **Private by default** -- always configure private endpoints for services that support them. Use conditional creation for flexibility. -5. **RBAC over keys** -- use managed identity role assignments. Disable shared key access where supported. -6. **Idempotent deployments** -- code must be safe to run multiple times without side effects. -7. **Tags everywhere** -- apply the standard tag set (Environment, Project, ManagedBy) to every resource and module. - -## Staged Deployment Understanding - -Infrastructure deploys in dependency order. The deploy script must enforce this sequence: - -| Stage | Contains | Depends On | -|-------|----------|------------| -| 1 - Foundation | Resource group, VNet/subnets, DNS zones, user-assigned managed identity, Log Analytics workspace, App Insights | None | -| 2 - Data | SQL, Cosmos DB, Storage accounts, Redis, Service Bus | Foundation (networking, identity, monitoring) | -| 3 - Compute | Container Apps Environment, Container Registry, App Service Plans, Function Apps | Foundation, Data | -| 4 - Applications | Container App definitions, API Management, application deployments | Compute | - -Each stage must: -- Validate prerequisites (prior stage outputs exist) -- Run plan/what-if before apply (always) -- Export outputs for subsequent stages -- Support `--dry-run` (plan-only mode) -- Support rollback (in reverse stage order) - -## POC-Specific Notes - -- **Local state** for Terraform (no remote backend setup). Document the migration path. -- **Consumption/serverless SKUs** preferred for cost efficiency. -- **Skip complex networking** when possible -- Container Apps can use internal ingress without a full VNet in simple scenarios. Include the private endpoint code but make it conditional (`enable_private_endpoint = false` for minimal POC). -- **Single resource group** unless the architect specifies otherwise. -- **deploy.sh must be executable** -- `chmod +x deploy.sh` and include proper error handling, usage messages, and stage selection. +# Infrastructure Agent Role + +Shared role template for the `terraform-agent` and `bicep-agent`. Both agents implement IaC for Azure services using their respective tools, directed by the `infrastructure-architect`. + +## Knowledge References + +Before generating IaC, load and internalize: + +- `../service-registry.yaml` — RBAC role IDs, private DNS zones, API versions, resource types +- `../tools/terraform.md` or `../tools/bicep.md` — tool-specific patterns and conventions +- `../tools/azapi-provider.md` — azapi provider configuration (terraform only) +- Project governance policies (loaded at runtime) +- Architecture design document (produced by cloud-architect) + +## Responsibilities + +1. **Per-stage IaC generation** — each deployment stage gets its own directory with complete, deployable code +2. **RBAC configuration** — assign managed identity roles using exact role IDs from `service-registry.yaml` +3. **Service-specific configuration** — SKUs, capacity, feature flags as specified by the architecture +4. **Staged deployment scripts** — `deploy.sh` per stage that handles init, plan, apply, destroy, and dry-run +5. **Output exports** — every value that downstream stages or application code might need +6. **Cross-stage references** — use `terraform_remote_state` (Terraform) or parameter inputs (Bicep) to reference prior stage outputs + +## What This Agent Does NOT Do + +- **Private endpoints** — created ONLY by the Networking stage, not per-service stages +- **Application code** — delegated to language-specific developers via the application-architect +- **Security design** — reviewed by the security-architect; this agent implements what the architects specify + +## File Structure + +### Terraform (per-stage directory) + +``` +concept/infra/terraform/stage-N-service-name/ +├── providers.tf # terraform {}, required_providers { azapi }, backend {}, provider "azapi" {} +├── main.tf # azapi_resource definitions — NO terraform {} or provider {} blocks +├── variables.tf # All input variable declarations with type and description +├── outputs.tf # All output value declarations +├── locals.tf # Computed local values (if needed) +├── deploy.sh # Deployment script with --dry-run, --destroy, --help flags +└── (optional) # identity.tf, rbac.tf, networking.tf for complex stages +``` + +**CRITICAL**: +- `providers.tf` is the ONLY file with `terraform {}`, `required_providers`, or `backend` +- Do NOT create `versions.tf` — it conflicts with `providers.tf` +- Use ONLY the `hashicorp/azapi` provider — NEVER `azurerm` +- `provider "azapi" {}` stays EMPTY — subscription context from az CLI +- Tags are a TOP-LEVEL attribute on `azapi_resource`, NEVER inside `body` + +### Bicep (per-stage directory) + +``` +concept/infra/bicep/stage-N-service-name/ +├── main.bicep # Resource definitions +├── main.bicepparam # Parameter file +├── deploy.sh # Deployment script +└── (optional) # modules/ for reusable components +``` + +## Standard Variables + +Every stage must accept these base inputs: + +```hcl +variable "resource_group_name" { + type = string + description = "Name of the resource group" +} + +variable "location" { + type = string + description = "Azure region for resources" +} + +variable "subscription_id" { + type = string + description = "Azure subscription ID — for ARM resource ID construction" +} + +variable "tenant_id" { + type = string + description = "Azure tenant ID" +} + +variable "tags" { + type = map(string) + description = "Tags to apply to all resources" + default = {} +} +``` + +## deploy.sh Requirements + +Every deployment script must include: +- `set -euo pipefail` +- Azure CLI login check (`az account show`) +- `az account set --subscription` + `export ARM_SUBSCRIPTION_ID` +- Error handling with `trap` +- Argument parsing: `--dry-run`, `--destroy`, `--help` +- Pre-flight validation of upstream stage outputs +- Post-deployment verification using `az` CLI commands +- Output export to JSON file diff --git a/azext_prototype/knowledge/roles/security-reviewer.md b/azext_prototype/knowledge/roles/security-architect.md similarity index 95% rename from azext_prototype/knowledge/roles/security-reviewer.md rename to azext_prototype/knowledge/roles/security-architect.md index 079b898..f1239f9 100644 --- a/azext_prototype/knowledge/roles/security-reviewer.md +++ b/azext_prototype/knowledge/roles/security-architect.md @@ -1,68 +1,68 @@ -# Security Reviewer Role - -## Knowledge References - -Before reviewing, load: -- `constraints.md` — the single source of truth for what is/isn't allowed -- Service knowledge files for any Azure services in the architecture -- Tool patterns for the IaC tool being used (terraform or bicep) - -## Responsibilities - -1. **Pre-deployment security scanning** — Review all generated IaC code before `az prototype deploy` executes -2. **Blocker identification** — Flag issues that MUST be fixed (hardcoded secrets, missing managed identity, overly permissive RBAC) -3. **Warning identification** — Flag issues that SHOULD be fixed but are acceptable for POC (public endpoints, missing VNET) -4. **Fix generation** — Provide exact corrected code for every finding, not just descriptions -5. **Backlog creation** — Classify deferred warnings with production priority (P1-P4) -6. **Architecture cross-reference** — Verify IaC code matches the approved architecture design - -## Review Categories - -### Critical (Always Blockers) -- **Authentication**: Connection strings, access keys, SQL auth, hardcoded credentials -- **RBAC**: Owner/Contributor on service identities, missing role assignments -- **Encryption**: TLS < 1.2, disabled encryption at rest -- **Network**: Wildcard (0.0.0.0/0) firewall rules - -### Important (Blockers or Warnings depending on context) -- **Key Vault**: Missing soft-delete, access policies instead of RBAC -- **Database**: Local auth not disabled, missing Advanced Threat Protection -- **Container Registry**: Admin credentials enabled -- **Tags**: Missing mandatory resource tags - -### POC-Acceptable (Warnings only) -- Public endpoints (document which services are exposed) -- Missing VNET integration -- Missing private endpoints -- Missing diagnostic logging on non-critical resources -- Single-region deployment -- Free/dev-tier SKUs without SLA - -## Output Format - -Every finding must include: -1. **Classification**: BLOCKER or WARNING -2. **ID**: Sequential (B-001, W-001) -3. **File reference**: Exact file path and resource name -4. **Issue description**: What is wrong -5. **Risk assessment**: What could happen -6. **Fix**: Exact corrected code -7. **Backlog priority** (warnings only): P1/P2/P3/P4 - -## Coordination - -| Agent | Interaction | -|-------|-------------| -| `terraform-agent` / `bicep-agent` | Reviews their generated output; sends blockers back for regeneration | -| `cloud-architect` | Consults on architectural security decisions; validates network design | -| `qa-engineer` | Shares findings; QA handles runtime issues, security-reviewer handles IaC | -| `app-developer` | Reviews application code for credential handling patterns | -| `project-manager` | Reports blocking findings that may affect scope or timeline | - -## Principles - -1. **Block early, not late** — Catch issues before deployment, not after -2. **Fix, don't just flag** — Every finding includes the corrected code -3. **POC-pragmatic** — Don't block prototypes for production-only concerns -4. **Reference the constraints** — All findings map back to `constraints.md` rules -5. **Zero false positives on blockers** — If you're unsure, classify as WARNING +# Security Reviewer Role + +## Knowledge References + +Before reviewing, load: +- `constraints.md` — the single source of truth for what is/isn't allowed +- Service knowledge files for any Azure services in the architecture +- Tool patterns for the IaC tool being used (terraform or bicep) + +## Responsibilities + +1. **Pre-deployment security scanning** — Review all generated IaC code before `az prototype deploy` executes +2. **Blocker identification** — Flag issues that MUST be fixed (hardcoded secrets, missing managed identity, overly permissive RBAC) +3. **Warning identification** — Flag issues that SHOULD be fixed (missing diagnostics, suboptimal SKUs) +4. **Fix generation** — Provide exact corrected code for every finding, not just descriptions +5. **Backlog creation** — Classify deferred warnings with production priority (P1-P4) +6. **Architecture cross-reference** — Verify IaC code matches the approved architecture design + +## Review Categories + +### Critical (Always Blockers) +- **Authentication**: Connection strings, access keys, SQL auth, hardcoded credentials +- **RBAC**: Owner/Contributor on service identities, missing role assignments +- **Encryption**: TLS < 1.2, disabled encryption at rest +- **Network**: Wildcard (0.0.0.0/0) firewall rules + +### Important (Blockers or Warnings depending on context) +- **Key Vault**: Missing soft-delete, access policies instead of RBAC +- **Database**: Local auth not disabled, missing Advanced Threat Protection +- **Container Registry**: Admin credentials enabled +- **Tags**: Missing mandatory resource tags + +### POC-Acceptable (Warnings only) +- Public endpoints (document which services are exposed) +- Missing VNET integration +- Missing private endpoints +- Missing diagnostic logging on non-critical resources +- Single-region deployment +- Free/dev-tier SKUs without SLA + +## Output Format + +Every finding must include: +1. **Classification**: BLOCKER or WARNING +2. **ID**: Sequential (B-001, W-001) +3. **File reference**: Exact file path and resource name +4. **Issue description**: What is wrong +5. **Risk assessment**: What could happen +6. **Fix**: Exact corrected code +7. **Backlog priority** (warnings only): P1/P2/P3/P4 + +## Coordination + +| Agent | Interaction | +|-------|-------------| +| `terraform-agent` / `bicep-agent` | Reviews their generated output; sends blockers back for regeneration | +| `cloud-architect` | Consults on architectural security decisions; validates network design | +| `qa-engineer` | Shares findings; QA handles runtime issues, security-reviewer handles IaC | +| `app-developer` | Reviews application code for credential handling patterns | +| `project-manager` | Reports blocking findings that may affect scope or timeline | + +## Principles + +1. **Block early, not late** — Catch issues before deployment, not after +2. **Fix, don't just flag** — Every finding includes the corrected code +3. **POC-pragmatic** — Don't block prototypes for production-only concerns +4. **Reference the constraints** — All findings map back to `constraints.md` rules +5. **Zero false positives on blockers** — If you're unsure, classify as WARNING diff --git a/azext_prototype/knowledge/search_cache.py b/azext_prototype/knowledge/search_cache.py index 874245a..de42f20 100644 --- a/azext_prototype/knowledge/search_cache.py +++ b/azext_prototype/knowledge/search_cache.py @@ -51,7 +51,7 @@ def get(self, query: str) -> str | None: return result def put(self, query: str, result: str) -> None: - """Store *result* under normalised *query* with the current timestamp.""" + """Store *result* under normalized *query* with the current timestamp.""" key = self._normalize(query) # Evict oldest if at capacity (and this is a new key) if key not in self._store and len(self._store) >= self._max_entries: diff --git a/azext_prototype/knowledge/service-registry.yaml b/azext_prototype/knowledge/service-registry.yaml index a9a94e8..65cfed5 100644 --- a/azext_prototype/knowledge/service-registry.yaml +++ b/azext_prototype/knowledge/service-registry.yaml @@ -1,885 +1,1081 @@ -# ============================================================================= -# Azure Service Registry - Canonical Reference -# ============================================================================= -# -# Single source of truth for Azure service configuration used by all agents at -# runtime. Contains RBAC role IDs, private DNS zones, API versions, SDK -# packages, and authentication scopes for every supported Azure service. -# -# Ported from the Innovation Factory SERVICE_REGISTRY.yaml and extended with -# additional services (event-grid, signalr, cognitive-search). Unlike the IF -# version, this extension deploys infrastructure directly -- there is no -# execution-policy restriction on running commands. -# -# Maintenance: -# - Keep bicep_api_version entries on current stable versions (2023-xx / 2024-xx) -# - When adding a new service, ensure ALL required fields are present -# - Validate with: python -m yaml service-registry.yaml -# ============================================================================= - -services: - - # --------------------------------------------------------------------------- - # Data & Storage - # --------------------------------------------------------------------------- - - azure-sql: - display_name: Azure SQL Database - resource_provider: Microsoft.Sql - terraform_resource: azurerm_mssql_server, azurerm_mssql_database - bicep_resource: Microsoft.Sql/servers, Microsoft.Sql/servers/databases - bicep_api_version: "2023-08-01-preview" - private_endpoint: - dns_zone: privatelink.database.windows.net - group_id: sqlServer - rbac_roles: - data_read: db_datareader (contained user) - data_write: db_datawriter (contained user) - admin: db_owner (contained user) - rbac_role_ids: {} - authentication: - method: Azure AD with Managed Identity - token_scope: https://database.windows.net/.default - notes: | - - Azure AD-only authentication must be enabled - - SQL authentication must be disabled - - Contained users created via T-SQL after deployment - sdk_packages: - dotnet: [Microsoft.Data.SqlClient, Azure.Identity] - python: [pyodbc, azure-identity] - nodejs: [tedious, "@azure/identity"] - special_considerations: - - Requires T-SQL script execution for user provisioning - - Cannot grant database roles via Terraform/Bicep - - Must use AAD admin for initial setup - - cosmos-db: - display_name: Azure Cosmos DB - resource_provider: Microsoft.DocumentDB - terraform_resource: azurerm_cosmosdb_account, azurerm_cosmosdb_sql_database - bicep_resource: Microsoft.DocumentDB/databaseAccounts - bicep_api_version: "2024-05-15" - private_endpoint: - dns_zone: privatelink.documents.azure.com - group_id: Sql - rbac_roles: - data_read: Cosmos DB Built-in Data Reader - data_write: Cosmos DB Built-in Data Contributor - admin: Cosmos DB Account Contributor - rbac_role_ids: - data_read: "00000000-0000-0000-0000-000000000001" - data_write: "00000000-0000-0000-0000-000000000002" - authentication: - method: RBAC with Managed Identity - token_scope: https://cosmos.azure.com/.default - notes: | - - Disable key-based metadata write access - - Use built-in RBAC roles (not custom) - sdk_packages: - dotnet: [Microsoft.Azure.Cosmos, Azure.Identity] - python: [azure-cosmos, azure-identity] - nodejs: ["@azure/cosmos", "@azure/identity"] - special_considerations: - - Partition key design is critical and hard to change - - Consider throughput mode (provisioned vs serverless) - - Multiple API types available (NoSQL, MongoDB, Cassandra, Gremlin, Table) - - blob-storage: - display_name: Azure Blob Storage - resource_provider: Microsoft.Storage - terraform_resource: azurerm_storage_account, azurerm_storage_container - bicep_resource: Microsoft.Storage/storageAccounts - bicep_api_version: "2023-05-01" - private_endpoint: - dns_zone: privatelink.blob.core.windows.net - group_id: blob - rbac_roles: - data_read: Storage Blob Data Reader - data_write: Storage Blob Data Contributor - admin: Storage Blob Data Owner - rbac_role_ids: - data_read: 2a2b9908-6ea1-4ae2-8e65-a410df84e7d1 - data_write: ba92f5b4-2d11-453d-a403-e96b0029c9fe - admin: b7e6dc6d-f1e8-4753-8033-0f276bb0955b - authentication: - method: RBAC with Managed Identity - token_scope: https://storage.azure.com/.default - notes: | - - Shared key access should be disabled when using RBAC - - Use user delegation SAS when temporary access is needed - sdk_packages: - dotnet: [Azure.Storage.Blobs, Azure.Identity] - python: [azure-storage-blob, azure-identity] - nodejs: ["@azure/storage-blob", "@azure/identity"] - special_considerations: - - Consider access tier (Hot, Cool, Archive) based on access patterns - - Lifecycle management policies for cost optimization - - redis-cache: - display_name: Azure Cache for Redis - resource_provider: Microsoft.Cache - terraform_resource: azurerm_redis_cache - bicep_resource: Microsoft.Cache/redis - bicep_api_version: "2024-03-01" - private_endpoint: - dns_zone: privatelink.redis.cache.windows.net - group_id: redisCache - rbac_roles: - data_read: Redis Cache Reader (Preview) - data_write: Redis Cache Contributor - rbac_role_ids: {} - authentication: - method: Azure AD with Managed Identity (requires AAD auth enabled) - token_scope: https://redis.azure.com/.default - notes: | - - AAD authentication must be explicitly enabled - - Access keys should be disabled when using AAD - sdk_packages: - dotnet: [StackExchange.Redis, Azure.Identity] - python: [redis, azure-identity] - nodejs: [ioredis, "@azure/identity"] - special_considerations: - - AAD auth is newer; verify customer's Redis version supports it - - Some legacy applications may require access keys - - # --------------------------------------------------------------------------- - # Messaging & Events - # --------------------------------------------------------------------------- - - service-bus: - display_name: Azure Service Bus - resource_provider: Microsoft.ServiceBus - terraform_resource: azurerm_servicebus_namespace, azurerm_servicebus_queue, azurerm_servicebus_topic - bicep_resource: Microsoft.ServiceBus/namespaces - bicep_api_version: "2024-01-01" - private_endpoint: - dns_zone: privatelink.servicebus.windows.net - group_id: namespace - rbac_roles: - data_read: Azure Service Bus Data Receiver - data_write: Azure Service Bus Data Sender - admin: Azure Service Bus Data Owner - rbac_role_ids: - data_read: 4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0 - data_write: 69a216fc-b8fb-44d8-bc22-1f3c2cd27a39 - admin: 090c5cfd-751d-490a-894a-3ce6f1109419 - authentication: - method: RBAC with Managed Identity - token_scope: https://servicebus.azure.net/.default - notes: | - - Shared access policies should be avoided in favor of RBAC - - Premium tier required for private endpoints - sdk_packages: - dotnet: [Azure.Messaging.ServiceBus, Azure.Identity] - python: [azure-servicebus, azure-identity] - nodejs: ["@azure/service-bus", "@azure/identity"] - special_considerations: - - Premium tier required for private endpoints and large messages - - Consider partitioning strategy for high-throughput scenarios - - event-grid: - display_name: Azure Event Grid - resource_provider: Microsoft.EventGrid - terraform_resource: azurerm_eventgrid_topic, azurerm_eventgrid_system_topic - bicep_resource: Microsoft.EventGrid/topics - bicep_api_version: "2024-06-01-preview" - private_endpoint: - dns_zone: privatelink.eventgrid.azure.net - group_id: topic - rbac_roles: - data_send: EventGrid Data Sender - contributor: EventGrid Contributor - rbac_role_ids: - data_send: d5a91429-5739-47e2-a06b-3470a27159e7 - authentication: - method: RBAC with Managed Identity - token_scope: https://eventgrid.azure.net/.default - notes: | - - Use RBAC for publishing; avoid SAS keys in new deployments - - System topics auto-created for Azure resource events - sdk_packages: - dotnet: [Azure.Messaging.EventGrid, Azure.Identity] - python: [azure-eventgrid, azure-identity] - nodejs: ["@azure/eventgrid", "@azure/identity"] - special_considerations: - - System topics vs custom topics serve different purposes - - Event subscriptions support filtering and dead-lettering - - CloudEvents schema recommended for new implementations - - # --------------------------------------------------------------------------- - # Security & Identity - # --------------------------------------------------------------------------- - - key-vault: - display_name: Azure Key Vault - resource_provider: Microsoft.KeyVault - terraform_resource: azurerm_key_vault, azurerm_key_vault_secret - bicep_resource: Microsoft.KeyVault/vaults - bicep_api_version: "2023-07-01" - private_endpoint: - dns_zone: privatelink.vaultcore.azure.net - group_id: vault - rbac_roles: - secrets_read: Key Vault Secrets User - secrets_write: Key Vault Secrets Officer - keys_read: Key Vault Crypto User - keys_write: Key Vault Crypto Officer - certs_read: Key Vault Certificate User - certs_write: Key Vault Certificates Officer - admin: Key Vault Administrator - rbac_role_ids: - secrets_read: 4633458b-17de-408a-b874-0445c86b69e6 - secrets_write: b86a8fe4-44ce-4948-aee5-eccb2c155cd7 - admin: 00482a5a-887f-4fb3-b363-3b7fe8e74483 - authentication: - method: RBAC with Managed Identity - token_scope: https://vault.azure.net/.default - notes: | - - Use RBAC mode (not access policies) for new vaults - - Soft delete and purge protection enabled by default - sdk_packages: - dotnet: [Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keys, Azure.Security.KeyVault.Certificates, Azure.Identity] - python: [azure-keyvault-secrets, azure-keyvault-keys, azure-keyvault-certificates, azure-identity] - nodejs: ["@azure/keyvault-secrets", "@azure/keyvault-keys", "@azure/keyvault-certificates", "@azure/identity"] - special_considerations: - - Use RBAC mode (not access policies) for new vaults - - Soft delete is enabled by default - - Purge protection recommended for production - - user-managed-identity: - display_name: User-Assigned Managed Identity - resource_provider: Microsoft.ManagedIdentity - terraform_resource: azurerm_user_assigned_identity - bicep_resource: Microsoft.ManagedIdentity/userAssignedIdentities - bicep_api_version: "2023-07-31-preview" - private_endpoint: - dns_zone: null - group_id: null - rbac_roles: - operator: Managed Identity Operator - contributor: Managed Identity Contributor - rbac_role_ids: {} - authentication: - method: null - token_scope: null - notes: | - - This resource IS the authentication mechanism for other services - - No authentication needed for the identity resource itself - sdk_packages: - dotnet: [Azure.Identity] - python: [azure-identity] - nodejs: ["@azure/identity"] - special_considerations: - - Create early in deployment sequence - - Assign to resources that need to authenticate - - RBAC roles assigned TO this identity for resource access - - # --------------------------------------------------------------------------- - # AI & Cognitive Services - # --------------------------------------------------------------------------- - - azure-openai: - display_name: Azure OpenAI Service - resource_provider: Microsoft.CognitiveServices - terraform_resource: azurerm_cognitive_account - bicep_resource: Microsoft.CognitiveServices/accounts - bicep_api_version: "2024-04-01-preview" - private_endpoint: - dns_zone: privatelink.openai.azure.com - group_id: account - rbac_roles: - data_read: Cognitive Services User - admin: Cognitive Services Contributor - rbac_role_ids: - data_read: a97b65f3-24c7-4388-baec-2e87135dc908 - admin: 25fbc0a9-bd7c-42a3-aa1a-3b75d497ee68 - authentication: - method: RBAC with Managed Identity - token_scope: https://cognitiveservices.azure.com/.default - notes: | - - Disable local (key-based) authentication for production - - Model deployments managed separately from account - sdk_packages: - dotnet: [Azure.AI.OpenAI, Azure.Identity] - python: [openai, azure-identity] - nodejs: [openai, "@azure/identity"] - special_considerations: - - Model deployments are separate from account creation - - Regional availability varies by model - - Quota limits apply per subscription/region - - Content filtering policies apply by default - - cognitive-search: - display_name: Azure AI Search - resource_provider: Microsoft.Search - terraform_resource: azurerm_search_service - bicep_resource: Microsoft.Search/searchServices - bicep_api_version: "2024-03-01-preview" - private_endpoint: - dns_zone: privatelink.search.windows.net - group_id: searchService - rbac_roles: - data_read: Search Index Data Reader - data_write: Search Index Data Contributor - admin: Search Service Contributor - rbac_role_ids: - data_read: 1407120a-92aa-4202-b7e9-c0e197c71c8f - data_write: 8ebe5a00-799e-43f5-93ac-243d3dce84a7 - authentication: - method: RBAC with Managed Identity or API key - token_scope: https://search.azure.com/.default - notes: | - - RBAC authentication preferred over API keys for production - - Disable API key access when RBAC is fully configured - - Supports both data-plane and control-plane RBAC - sdk_packages: - dotnet: [Azure.Search.Documents, Azure.Identity] - python: [azure-search-documents, azure-identity] - nodejs: ["@azure/search-documents", "@azure/identity"] - special_considerations: - - Index schema changes may require reindexing - - Semantic ranking requires Standard tier or higher - - Integrated vectorization available for AI-enriched search - - Skillsets enable AI enrichment during indexing - - # --------------------------------------------------------------------------- - # Compute & Containers - # --------------------------------------------------------------------------- - - container-apps: - display_name: Azure Container Apps - resource_provider: Microsoft.App - terraform_resource: azurerm_container_app, azurerm_container_app_environment - bicep_resource: Microsoft.App/containerApps, Microsoft.App/managedEnvironments - bicep_api_version: "2024-03-01" - private_endpoint: - dns_zone: null - group_id: null - rbac_roles: - contributor: Contributor (scoped to app) - rbac_role_ids: {} - authentication: - method: User-Assigned Managed Identity attached to app - token_scope: null - notes: | - - Identity assigned at container app level - - Uses workload identity for outbound connections - - No private endpoint; VNet integration via environment - sdk_packages: - dotnet: [Azure.ResourceManager.AppContainers, Azure.Identity] - python: [azure-mgmt-appcontainers, azure-identity] - nodejs: ["@azure/arm-appcontainers", "@azure/identity"] - special_considerations: - - Requires Container Apps Environment (with Log Analytics workspace) - - Requires Container Registry for images - - Ingress configuration determines public/private access - - Environment provides VNet integration (not private endpoints) - - container-registry: - display_name: Azure Container Registry - resource_provider: Microsoft.ContainerRegistry - terraform_resource: azurerm_container_registry - bicep_resource: Microsoft.ContainerRegistry/registries - bicep_api_version: "2023-11-01-preview" - private_endpoint: - dns_zone: privatelink.azurecr.io - group_id: registry - rbac_roles: - pull: AcrPull - push: AcrPush - admin: AcrImageSigner - rbac_role_ids: - pull: 7f951dda-4ed3-4680-a7ca-43fe172d538d - push: 8311e382-0749-4cb8-b61a-304f252e45ec - authentication: - method: RBAC with Managed Identity - token_scope: null - notes: | - - Admin user should be disabled - - Use AcrPull role for container runtimes - - Token-based repository-scoped access available - sdk_packages: - dotnet: [Azure.Containers.ContainerRegistry, Azure.Identity] - python: [azure-containerregistry, azure-identity] - nodejs: ["@azure/container-registry", "@azure/identity"] - special_considerations: - - Premium tier required for private endpoints and geo-replication - - Image vulnerability scanning available with Defender for Containers - - azure-functions: - display_name: Azure Functions - resource_provider: Microsoft.Web - terraform_resource: azurerm_linux_function_app, azurerm_windows_function_app - bicep_resource: Microsoft.Web/sites - bicep_api_version: "2023-12-01" - private_endpoint: - dns_zone: privatelink.azurewebsites.net - group_id: sites - rbac_roles: - contributor: Website Contributor - rbac_role_ids: {} - authentication: - method: User-Assigned Managed Identity attached to function app - token_scope: null - notes: | - - Identity assigned at function app level - - Use managed identity for connections to other Azure services - sdk_packages: - dotnet: [Microsoft.Azure.Functions.Worker, Azure.Identity] - python: [azure-functions, azure-identity] - nodejs: ["@azure/functions", "@azure/identity"] - special_considerations: - - Requires App Service Plan or Consumption plan - - Requires Storage Account for runtime - - Can use VNet integration for outbound - - Flex Consumption plan offers per-function scaling - - app-service: - display_name: Azure Web App (App Service) - resource_provider: Microsoft.Web - terraform_resource: azurerm_linux_web_app, azurerm_windows_web_app, azurerm_service_plan - bicep_resource: Microsoft.Web/sites, Microsoft.Web/serverfarms - bicep_api_version: "2023-12-01" - private_endpoint: - dns_zone: privatelink.azurewebsites.net - group_id: sites - rbac_roles: - contributor: Website Contributor - rbac_role_ids: {} - authentication: - method: User-Assigned Managed Identity attached to web app - token_scope: null - notes: | - - Identity assigned at web app level - - Easy Auth available for end-user authentication - sdk_packages: - dotnet: [Azure.ResourceManager.AppService, Azure.Identity] - python: [azure-mgmt-web, azure-identity] - nodejs: ["@azure/arm-appservice", "@azure/identity"] - special_considerations: - - Requires App Service Plan - - Can use VNet integration for outbound - - Supports deployment slots - - Always-on setting required for production workloads - - # --------------------------------------------------------------------------- - # API & Integration - # --------------------------------------------------------------------------- - - api-management: - display_name: Azure API Management - resource_provider: Microsoft.ApiManagement - terraform_resource: azurerm_api_management - bicep_resource: Microsoft.ApiManagement/service - bicep_api_version: "2023-09-01-preview" - private_endpoint: - dns_zone: privatelink.azure-api.net - group_id: Gateway - rbac_roles: - reader: API Management Service Reader - contributor: API Management Service Contributor - rbac_role_ids: {} - authentication: - method: Managed Identity for backend authentication - token_scope: null - notes: | - - Use managed identity for authenticating to backend APIs - - Configure authentication policies in APIM - - Subscription keys for consumer-facing access control - sdk_packages: - dotnet: [Azure.ResourceManager.ApiManagement, Azure.Identity] - python: [azure-mgmt-apimanagement, azure-identity] - nodejs: ["@azure/arm-apimanagement", "@azure/identity"] - special_considerations: - - Long deployment times (30-45 minutes) - - Multiple SKU tiers with different capabilities - - VNet integration modes (external/internal) - - v2 SKUs offer faster deployment and scaling - - signalr: - display_name: Azure SignalR Service - resource_provider: Microsoft.SignalRService - terraform_resource: azurerm_signalr_service - bicep_resource: Microsoft.SignalRService/signalR - bicep_api_version: "2024-03-01" - private_endpoint: - dns_zone: privatelink.service.signalr.net - group_id: signalr - rbac_roles: - app_server: SignalR App Server - admin: SignalR Service Owner - rbac_role_ids: {} - authentication: - method: RBAC with Managed Identity - token_scope: null - notes: | - - Use AAD authentication instead of connection strings in production - - SignalR App Server role required for server-side connections - sdk_packages: - dotnet: [Microsoft.Azure.SignalR, Azure.Identity] - python: [] - nodejs: ["@microsoft/signalr", "@azure/identity"] - special_considerations: - - No dedicated Python SDK; use REST API or Azure Functions bindings - - Serverless mode available for event-driven architectures - - Consider connection limits per unit - - Upstream URL configuration for serverless mode - - # --------------------------------------------------------------------------- - # Monitoring & Observability - # --------------------------------------------------------------------------- - - app-insights: - display_name: Application Insights - resource_provider: Microsoft.Insights - terraform_resource: azurerm_application_insights - bicep_resource: Microsoft.Insights/components - bicep_api_version: "2020-02-02" - private_endpoint: - dns_zone: null - group_id: null - rbac_roles: - reader: Application Insights Component Reader - contributor: Application Insights Component Contributor - rbac_role_ids: {} - authentication: - method: Connection string or Managed Identity - token_scope: null - notes: | - - Modern SDKs support AAD authentication - - Connection string does not contain secrets (just instrumentation key) - - OpenTelemetry-based SDKs recommended for new projects - sdk_packages: - dotnet: [Microsoft.ApplicationInsights.AspNetCore, Azure.Monitor.OpenTelemetry.AspNetCore] - python: [opencensus-ext-azure, azure-monitor-opentelemetry] - nodejs: [applicationinsights, "@azure/monitor-opentelemetry"] - special_considerations: - - Requires Log Analytics workspace - - Connection string safe to include in config (not a secret) - - OpenTelemetry distro is the modern recommended approach - - log-analytics: - display_name: Log Analytics Workspace - resource_provider: Microsoft.OperationalInsights - terraform_resource: azurerm_log_analytics_workspace - bicep_resource: Microsoft.OperationalInsights/workspaces - bicep_api_version: "2023-09-01" - private_endpoint: - dns_zone: privatelink.oms.opinsights.azure.com - group_id: azuremonitor - rbac_roles: - reader: Log Analytics Reader - contributor: Log Analytics Contributor - rbac_role_ids: - reader: 73c42c96-874c-492b-b04d-ab87d138a893 - contributor: 92aaf0da-9dab-42b6-94a3-d43ce8d16293 - authentication: - method: RBAC with Managed Identity - token_scope: https://api.loganalytics.io/.default - notes: | - - Query access controlled via RBAC - - Data collection rules manage ingestion - sdk_packages: - dotnet: [Azure.Monitor.Query, Azure.Identity] - python: [azure-monitor-query, azure-identity] - nodejs: ["@azure/monitor-query", "@azure/identity"] - special_considerations: - - Foundation for most monitoring scenarios - - Required by App Insights, Container Apps Environment - - Consider data retention settings and cost implications - - Dedicated clusters available for high-volume scenarios - - # --------------------------------------------------------------------------- - # Additional Compute - # --------------------------------------------------------------------------- - - aks: - display_name: Azure Kubernetes Service - resource_provider: Microsoft.ContainerService - terraform_resource: azurerm_kubernetes_cluster - bicep_resource: Microsoft.ContainerService/managedClusters - bicep_api_version: "2024-03-02-preview" - private_endpoint: - dns_zone: privatelink..azmk8s.io - group_id: management - rbac_roles: - cluster_user: Azure Kubernetes Service Cluster User Role - rbac_admin: Azure Kubernetes Service RBAC Admin - rbac_writer: Azure Kubernetes Service RBAC Writer - rbac_reader: Azure Kubernetes Service RBAC Reader - rbac_role_ids: - cluster_user: 4abbcc35-e782-43d8-92c5-2d3f1bd2253f - rbac_admin: 3498e952-d568-435e-9b2c-8d77e338d7f7 - rbac_writer: a7ffa36f-339b-4b5c-8bdf-e2c188b2c0eb - rbac_reader: 7f6c6a51-bcf8-42ba-9220-52d62157d06d - authentication: - method: Azure AD + Kubernetes RBAC with Workload Identity - token_scope: 6dae42f8-4368-4678-94ff-3960e28e3630/.default - notes: | - - Workload identity for pod-level Azure service access - - OIDC issuer must be enabled on cluster - - Federated identity credentials link K8s service accounts to Azure identities - sdk_packages: - dotnet: [Azure.ResourceManager.ContainerService, Azure.Identity] - python: [azure-mgmt-containerservice, azure-identity] - nodejs: ["@azure/arm-containerservice", "@azure/identity"] - special_considerations: - - Network plugin choice (Azure CNI vs kubenet) is permanent - - System node pool minimum VM size is Standard_B2s - - AcrPull role must be on kubelet identity, not cluster identity - - Private cluster requires VPN/bastion for API server access - - virtual-machines: - display_name: Azure Virtual Machines - resource_provider: Microsoft.Compute - terraform_resource: azurerm_linux_virtual_machine, azurerm_windows_virtual_machine - bicep_resource: Microsoft.Compute/virtualMachines - bicep_api_version: "2024-03-01" - private_endpoint: - dns_zone: null - group_id: null - rbac_roles: - contributor: Virtual Machine Contributor - admin_login: Virtual Machine Administrator Login - user_login: Virtual Machine User Login - rbac_role_ids: - contributor: 9980e02c-c2be-4d73-94e8-173b1dc7cf3c - admin_login: 1c0163c0-47e6-4577-8991-ea5c82e286e4 - user_login: fb879df8-f326-4884-b1cf-06f3ad86be52 - authentication: - method: SSH key (Linux) or password (Windows) + Azure AD login - token_scope: null - notes: | - - Always use SSH keys for Linux (never passwords) - - Managed identity for Azure service access from VM - - Azure AD login available as alternative to local accounts - sdk_packages: - dotnet: [Azure.ResourceManager.Compute, Azure.Identity] - python: [azure-mgmt-compute, azure-identity] - nodejs: ["@azure/arm-compute", "@azure/identity"] - special_considerations: - - VMs are IaaS -- require OS patching and security hardening - - Always configure auto-shutdown for non-production - - Use Azure Bastion instead of public IPs for management - - Windows VM names limited to 15 characters - - static-web-apps: - display_name: Azure Static Web Apps - resource_provider: Microsoft.Web - terraform_resource: azurerm_static_web_app - bicep_resource: Microsoft.Web/staticSites - bicep_api_version: "2023-12-01" - private_endpoint: - dns_zone: privatelink.azurestaticapps.net - group_id: staticSites - rbac_roles: - contributor: Website Contributor - rbac_role_ids: {} - authentication: - method: Deployment token (API key) for CI/CD - token_scope: null - notes: | - - Built-in auth providers (GitHub, Azure AD, Twitter) - - Custom auth available on Standard tier - - API key used for deployment, not data access - sdk_packages: - dotnet: [Azure.ResourceManager.AppService, Azure.Identity] - python: [azure-mgmt-web, azure-identity] - nodejs: ["@azure/arm-appservice", "@azure/identity"] - special_considerations: - - Free tier has no SLA - - Managed Functions only support Node.js and Python - - All API routes must start with /api/ - - Standard tier required for private endpoints and linked backends - - # --------------------------------------------------------------------------- - # Networking - # --------------------------------------------------------------------------- - - front-door: - display_name: Azure Front Door - resource_provider: Microsoft.Cdn - terraform_resource: azurerm_cdn_frontdoor_profile, azurerm_cdn_frontdoor_endpoint - bicep_resource: Microsoft.Cdn/profiles - bicep_api_version: "2024-02-01" - private_endpoint: - dns_zone: null - group_id: null - rbac_roles: - contributor: CDN Profile Contributor - reader: CDN Profile Reader - rbac_role_ids: {} - authentication: - method: null - token_scope: null - notes: | - - Front Door is a reverse proxy; no data-plane auth - - WAF policies for request filtering (Premium tier) - - Private Link origins for secure backend connectivity (Premium tier) - sdk_packages: - dotnet: [Azure.ResourceManager.Cdn, Azure.Identity] - python: [azure-mgmt-cdn, azure-identity] - nodejs: ["@azure/arm-cdn", "@azure/identity"] - special_considerations: - - Standard = CDN + routing; Premium = WAF + Private Link origins - - Profile changes take 10-20 minutes to propagate globally - - WAF policy names cannot contain hyphens - - DNS CNAME validation required for custom domains - - # --------------------------------------------------------------------------- - # Data & Analytics - # --------------------------------------------------------------------------- - - postgresql: - display_name: Azure Database for PostgreSQL (Flexible Server) - resource_provider: Microsoft.DBforPostgreSQL - terraform_resource: azurerm_postgresql_flexible_server, azurerm_postgresql_flexible_server_database - bicep_resource: Microsoft.DBforPostgreSQL/flexibleServers - bicep_api_version: "2023-12-01-preview" - private_endpoint: - dns_zone: privatelink.postgres.database.azure.com - group_id: postgresqlServer - rbac_roles: - data_read: db_datareader (contained user) - data_write: db_datawriter (contained user) - admin: azure_pg_admin (server role) - rbac_role_ids: {} - authentication: - method: Azure AD with Managed Identity + password for admin - token_scope: https://ossrdbms-aad.database.windows.net/.default - notes: | - - AAD auth enabled alongside password auth - - Managed identity creates AAD database roles via SQL - - Token refresh needed for long connections (~1 hour expiry) - sdk_packages: - dotnet: [Npgsql, Azure.Identity] - python: [psycopg2-binary, azure-identity] - nodejs: [pg, "@azure/identity"] - special_considerations: - - VNet integration (delegated subnet) is set at creation time - - AAD role creation requires AAD admin to run SQL commands post-deployment - - pgvector extension must be explicitly enabled - - Burstable tier has limited IOPS - - azure-ai-search: - display_name: Azure AI Search - resource_provider: Microsoft.Search - terraform_resource: azurerm_search_service - bicep_resource: Microsoft.Search/searchServices - bicep_api_version: "2024-03-01-preview" - private_endpoint: - dns_zone: privatelink.search.windows.net - group_id: searchService - rbac_roles: - data_read: Search Index Data Reader - data_write: Search Index Data Contributor - admin: Search Service Contributor - rbac_role_ids: - data_read: 1407120a-92aa-4202-b7e9-c0e197c71c8f - data_write: 8ebe5a00-799e-43f5-93ac-243d3dce84a7 - admin: 7ca78c08-252a-4471-8644-bb5ff32d4ba0 - authentication: - method: RBAC with Managed Identity or API key - token_scope: https://search.azure.com/.default - notes: | - - RBAC preferred over API keys for production - - Set disableLocalAuth=true when RBAC fully configured - - Supports both data-plane and control-plane RBAC - sdk_packages: - dotnet: [Azure.Search.Documents, Azure.Identity] - python: [azure-search-documents, azure-identity] - nodejs: ["@azure/search-documents", "@azure/identity"] - special_considerations: - - Index schema changes may require full reindex - - Semantic ranker free tier limited to 1000 queries/month - - Vector dimensions must match embedding model - - Integrated vectorization is preview; push model more mature - - databricks: - display_name: Azure Databricks - resource_provider: Microsoft.Databricks - terraform_resource: azurerm_databricks_workspace - bicep_resource: Microsoft.Databricks/workspaces - bicep_api_version: "2024-05-01" - private_endpoint: - dns_zone: privatelink.azuredatabricks.net - group_id: databricks_ui_api - rbac_roles: - contributor: Contributor (scoped to workspace) - rbac_role_ids: {} - authentication: - method: Azure AD for workspace access; Unity Catalog for data - token_scope: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default - notes: | - - Workspace access via Azure AD SSO - - Data access via Unity Catalog grants (not ARM RBAC) - - Databricks secret scopes for credential management - sdk_packages: - dotnet: [Azure.ResourceManager.Databricks, Azure.Identity] - python: [databricks-sdk, azure-identity] - nodejs: ["@azure/arm-databricks", "@azure/identity"] - special_considerations: - - Premium tier required for Unity Catalog, RBAC, audit logs - - VNet injection subnet sizing critical (/26 minimum) - - DBU pricing varies by workload type (Jobs < All-Purpose) - - Managed resource group must not already exist - - data-factory: - display_name: Azure Data Factory - resource_provider: Microsoft.DataFactory - terraform_resource: azurerm_data_factory - bicep_resource: Microsoft.DataFactory/factories - bicep_api_version: "2018-06-01" - private_endpoint: - dns_zone: privatelink.datafactory.azure.net - group_id: dataFactory - rbac_roles: - contributor: Data Factory Contributor - rbac_role_ids: - contributor: 673868aa-7521-48a0-acc6-0f60742d39f5 - authentication: - method: Managed Identity for data source connections - token_scope: null - notes: | - - ADF managed identity authenticates to data sources - - Grant identity RBAC roles on each connected resource - - Self-hosted IR for on-premises data sources - sdk_packages: - dotnet: [Azure.ResourceManager.DataFactory, Azure.Identity] - python: [azure-mgmt-datafactory, azure-identity] - nodejs: ["@azure/arm-datafactory", "@azure/identity"] - special_considerations: - - Self-hosted integration runtime needed for on-premises - - Mapping data flow has 3-5 minute cold start - - Pipeline JSON ordering causes Terraform plan drift - - Schedule triggers default to UTC timezone - - fabric: - display_name: Microsoft Fabric - resource_provider: Microsoft.Fabric - terraform_resource: azurerm_fabric_capacity - bicep_resource: Microsoft.Fabric/capacities - bicep_api_version: "2023-11-01" - private_endpoint: - dns_zone: null - group_id: fabric - rbac_roles: - contributor: Contributor (scoped to capacity) - rbac_role_ids: {} - authentication: - method: Azure AD for Fabric portal; workspace roles for data - token_scope: https://api.fabric.microsoft.com/.default - notes: | - - Capacity is ARM-deployed; workspaces are Fabric-managed - - Workspace roles (Admin/Member/Contributor/Viewer) via Fabric API - - OneLake access governed by workspace permissions - sdk_packages: - dotnet: [Azure.ResourceManager.Fabric, Azure.Identity] - python: [azure-mgmt-fabric, azure-identity] - nodejs: ["@azure/arm-fabric", "@azure/identity"] - special_considerations: - - Capacity vs workspace distinction (ARM vs SaaS) - - F2 is smallest capacity SKU (~$0.36/hr) - - 60-day free trial available per tenant - - No VNet injection; use managed private endpoints - - Workspaces cannot be created via Terraform/Bicep +# ============================================================================= +# Azure Service Registry — Keyed by ARM Resource Type Namespace +# ============================================================================= +# +# Single source of truth for Azure service configuration. Each entry is keyed +# by its ARM resource type namespace (e.g., Microsoft.Sql/servers). Contains +# RBAC role IDs, private DNS zones, API versions, SDK packages, and auth scopes. +# +# Services sharing an ARM namespace (e.g., Microsoft.Web/sites for both App +# Service and Functions) use a #kind suffix to disambiguate. +# +# The friendly_name field maps back to discovery-phase service names. +# The architect deployment plan translates friendly names to namespaces. +# ============================================================================= + +services: + Microsoft.Sql/servers: + display_name: Azure SQL Server + resource_provider: Microsoft.Sql + resource_type: Microsoft.Sql/servers + api_version: 2023-08-01-preview + private_endpoint: + dns_zone: privatelink.database.windows.net + group_id: sqlServer + rbac_roles: + data_read: db_datareader (contained user) + data_write: db_datawriter (contained user) + admin: db_owner (contained user) + rbac_role_ids: {} + authentication: + method: Azure AD with Managed Identity + token_scope: https://database.windows.net/.default + notes: | + - Azure AD-only authentication must be enabled + - SQL authentication must be disabled + - Contained users created via T-SQL after deployment + sdk_packages: + dotnet: + - Microsoft.Data.SqlClient + - Azure.Identity + python: + - pyodbc + - azure-identity + nodejs: + - tedious + - '@azure/identity' + special_considerations: + - Requires T-SQL script execution for user provisioning + - Cannot grant database roles via Terraform/Bicep + - Must use AAD admin for initial setup + friendly_name: azure-sql + Microsoft.Sql/servers/databases: + display_name: Azure SQL Database + resource_provider: Microsoft.Sql + resource_type: Microsoft.Sql/servers/databases + api_version: 2023-08-01-preview + private_endpoint: + dns_zone: privatelink.database.windows.net + group_id: sqlServer + rbac_roles: + data_read: db_datareader (contained user) + data_write: db_datawriter (contained user) + admin: db_owner (contained user) + rbac_role_ids: {} + authentication: + method: Azure AD with Managed Identity + token_scope: https://database.windows.net/.default + notes: | + - Azure AD-only authentication must be enabled + - SQL authentication must be disabled + - Contained users created via T-SQL after deployment + sdk_packages: + dotnet: + - Microsoft.Data.SqlClient + - Azure.Identity + python: + - pyodbc + - azure-identity + nodejs: + - tedious + - '@azure/identity' + special_considerations: + - Requires T-SQL script execution for user provisioning + - Cannot grant database roles via Terraform/Bicep + - Must use AAD admin for initial setup + friendly_name: azure-sql-database + depends_on: + - Microsoft.Sql/servers + Microsoft.DocumentDB/databaseAccounts: + display_name: Azure Cosmos DB + resource_provider: Microsoft.DocumentDB + resource_type: Microsoft.DocumentDB/databaseAccounts + api_version: '2024-05-15' + private_endpoint: + dns_zone: privatelink.documents.azure.com + group_id: Sql + rbac_roles: + data_read: Cosmos DB Built-in Data Reader + data_write: Cosmos DB Built-in Data Contributor + admin: Cosmos DB Account Contributor + rbac_role_ids: + data_read: 00000000-0000-0000-0000-000000000001 + data_write: 00000000-0000-0000-0000-000000000002 + authentication: + method: RBAC with Managed Identity + token_scope: https://cosmos.azure.com/.default + notes: | + - Disable key-based metadata write access + - Use built-in RBAC roles (not custom) + sdk_packages: + dotnet: + - Microsoft.Azure.Cosmos + - Azure.Identity + python: + - azure-cosmos + - azure-identity + nodejs: + - '@azure/cosmos' + - '@azure/identity' + child_resources: + sqlRoleAssignments: + resource_type: Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments + api_version: '2024-05-15' + sqlRoleDefinitions: + resource_type: Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions + api_version: '2024-05-15' + sqlDatabases: + resource_type: Microsoft.DocumentDB/databaseAccounts/sqlDatabases + api_version: '2024-05-15' + sqlContainers: + resource_type: Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers + api_version: '2024-05-15' + special_considerations: + - Partition key design is critical and hard to change + - Consider throughput mode (provisioned vs serverless) + - Multiple API types available (NoSQL, MongoDB, Cassandra, Gremlin, Table) + - sqlRoleAssignments use Cosmos-specific RBAC, NOT ARM roleAssignments + friendly_name: cosmos-db + Microsoft.Storage/storageAccounts: + display_name: Azure Blob Storage + resource_provider: Microsoft.Storage + resource_type: Microsoft.Storage/storageAccounts + api_version: '2023-05-01' + private_endpoint: + dns_zone: privatelink.blob.core.windows.net + group_id: blob + rbac_roles: + data_read: Storage Blob Data Reader + data_write: Storage Blob Data Contributor + admin: Storage Blob Data Owner + rbac_role_ids: + data_read: 2a2b9908-6ea1-4ae2-8e65-a410df84e7d1 + data_write: ba92f5b4-2d11-453d-a403-e96b0029c9fe + admin: b7e6dc6d-f1e8-4753-8033-0f276bb0955b + authentication: + method: RBAC with Managed Identity + token_scope: https://storage.azure.com/.default + notes: | + - Shared key access should be disabled when using RBAC + - Use user delegation SAS when temporary access is needed + sdk_packages: + dotnet: + - Azure.Storage.Blobs + - Azure.Identity + python: + - azure-storage-blob + - azure-identity + nodejs: + - '@azure/storage-blob' + - '@azure/identity' + child_resources: + blobServices/containers: + api_version: '2023-05-01' + special_considerations: + - Consider access tier (Hot, Cool, Archive) based on access patterns + - Lifecycle management policies for cost optimization + friendly_name: blob-storage + Microsoft.Cache/redis: + display_name: Azure Cache for Redis + resource_provider: Microsoft.Cache + resource_type: Microsoft.Cache/redis + api_version: '2024-03-01' + private_endpoint: + dns_zone: privatelink.redis.cache.windows.net + group_id: redisCache + rbac_roles: + data_read: Redis Cache Reader (Preview) + data_write: Redis Cache Contributor + rbac_role_ids: {} + authentication: + method: Azure AD with Managed Identity (requires AAD auth enabled) + token_scope: https://redis.azure.com/.default + notes: | + - AAD authentication must be explicitly enabled + - Access keys should be disabled when using AAD + sdk_packages: + dotnet: + - StackExchange.Redis + - Azure.Identity + python: + - redis + - azure-identity + nodejs: + - ioredis + - '@azure/identity' + special_considerations: + - AAD auth is newer; verify customer's Redis version supports it + - Some legacy applications may require access keys + friendly_name: redis-cache + Microsoft.ServiceBus/namespaces: + display_name: Azure Service Bus + resource_provider: Microsoft.ServiceBus + resource_type: Microsoft.ServiceBus/namespaces + api_version: '2024-01-01' + private_endpoint: + dns_zone: privatelink.servicebus.windows.net + group_id: namespace + rbac_roles: + data_read: Azure Service Bus Data Receiver + data_write: Azure Service Bus Data Sender + admin: Azure Service Bus Data Owner + rbac_role_ids: + data_read: 4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0 + data_write: 69a216fc-b8fb-44d8-bc22-1f3c2cd27a39 + admin: 090c5cfd-751d-490a-894a-3ce6f1109419 + authentication: + method: RBAC with Managed Identity + token_scope: https://servicebus.azure.net/.default + notes: | + - Shared access policies should be avoided in favor of RBAC + - Premium tier required for private endpoints + sdk_packages: + dotnet: + - Azure.Messaging.ServiceBus + - Azure.Identity + python: + - azure-servicebus + - azure-identity + nodejs: + - '@azure/service-bus' + - '@azure/identity' + special_considerations: + - Premium tier required for private endpoints and large messages + - Consider partitioning strategy for high-throughput scenarios + friendly_name: service-bus + Microsoft.EventGrid/topics: + display_name: Azure Event Grid + resource_provider: Microsoft.EventGrid + resource_type: Microsoft.EventGrid/topics + api_version: 2024-06-01-preview + private_endpoint: + dns_zone: privatelink.eventgrid.azure.net + group_id: topic + rbac_roles: + data_send: EventGrid Data Sender + contributor: EventGrid Contributor + rbac_role_ids: + data_send: d5a91429-5739-47e2-a06b-3470a27159e7 + authentication: + method: RBAC with Managed Identity + token_scope: https://eventgrid.azure.net/.default + notes: | + - Use RBAC for publishing; avoid SAS keys in new deployments + - System topics auto-created for Azure resource events + sdk_packages: + dotnet: + - Azure.Messaging.EventGrid + - Azure.Identity + python: + - azure-eventgrid + - azure-identity + nodejs: + - '@azure/eventgrid' + - '@azure/identity' + special_considerations: + - System topics vs custom topics serve different purposes + - Event subscriptions support filtering and dead-lettering + - CloudEvents schema recommended for new implementations + friendly_name: event-grid + Microsoft.KeyVault/vaults: + display_name: Azure Key Vault + resource_provider: Microsoft.KeyVault + resource_type: Microsoft.KeyVault/vaults + api_version: '2023-07-01' + private_endpoint: + dns_zone: privatelink.vaultcore.azure.net + group_id: vault + rbac_roles: + secrets_read: Key Vault Secrets User + secrets_write: Key Vault Secrets Officer + keys_read: Key Vault Crypto User + keys_write: Key Vault Crypto Officer + certs_read: Key Vault Certificate User + certs_write: Key Vault Certificates Officer + admin: Key Vault Administrator + rbac_role_ids: + secrets_read: 4633458b-17de-408a-b874-0445c86b69e6 + secrets_write: b86a8fe4-44ce-4948-aee5-eccb2c155cd7 + admin: 00482a5a-887f-4fb3-b363-3b7fe8e74483 + authentication: + method: RBAC with Managed Identity + token_scope: https://vault.azure.net/.default + notes: | + - Use RBAC mode (not access policies) for new vaults + - Soft delete and purge protection enabled by default + sdk_packages: + dotnet: + - Azure.Security.KeyVault.Secrets + - Azure.Security.KeyVault.Keys + - Azure.Security.KeyVault.Certificates + - Azure.Identity + python: + - azure-keyvault-secrets + - azure-keyvault-keys + - azure-keyvault-certificates + - azure-identity + nodejs: + - '@azure/keyvault-secrets' + - '@azure/keyvault-keys' + - '@azure/keyvault-certificates' + - '@azure/identity' + special_considerations: + - Use RBAC mode (not access policies) for new vaults + - Soft delete is enabled by default + - Purge protection recommended for production + friendly_name: key-vault + Microsoft.ManagedIdentity/userAssignedIdentities: + display_name: User-Assigned Managed Identity + resource_provider: Microsoft.ManagedIdentity + resource_type: Microsoft.ManagedIdentity/userAssignedIdentities + api_version: 2023-07-31-preview + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + operator: Managed Identity Operator + contributor: Managed Identity Contributor + rbac_role_ids: {} + authentication: + method: null + token_scope: null + notes: | + - This resource IS the authentication mechanism for other services + - No authentication needed for the identity resource itself + sdk_packages: + dotnet: + - Azure.Identity + python: + - azure-identity + nodejs: + - '@azure/identity' + special_considerations: + - Create early in deployment sequence + - Assign to resources that need to authenticate + - RBAC roles assigned TO this identity for resource access + friendly_name: user-managed-identity + Microsoft.CognitiveServices/accounts: + display_name: Azure OpenAI Service + resource_provider: Microsoft.CognitiveServices + resource_type: Microsoft.CognitiveServices/accounts + api_version: 2024-04-01-preview + private_endpoint: + dns_zone: privatelink.openai.azure.com + group_id: account + rbac_roles: + data_read: Cognitive Services User + admin: Cognitive Services Contributor + rbac_role_ids: + data_read: a97b65f3-24c7-4388-baec-2e87135dc908 + admin: 25fbc0a9-bd7c-42a3-aa1a-3b75d497ee68 + authentication: + method: RBAC with Managed Identity + token_scope: https://cognitiveservices.azure.com/.default + notes: | + - Disable local (key-based) authentication for production + - Model deployments managed separately from account + sdk_packages: + dotnet: + - Azure.AI.OpenAI + - Azure.Identity + python: + - openai + - azure-identity + nodejs: + - openai + - '@azure/identity' + special_considerations: + - Model deployments are separate from account creation + - Regional availability varies by model + - Quota limits apply per subscription/region + - Content filtering policies apply by default + friendly_name: azure-openai + Microsoft.App/containerApps: + display_name: Azure Container App + resource_provider: Microsoft.App + resource_type: Microsoft.App/containerApps + api_version: '2024-03-01' + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + contributor: Contributor (scoped to app) + rbac_role_ids: {} + authentication: + method: User-Assigned Managed Identity attached to app + token_scope: null + notes: | + - Identity assigned at container app level + - Uses workload identity for outbound connections + - No private endpoint; VNet integration via environment + sdk_packages: + dotnet: + - Azure.ResourceManager.AppContainers + - Azure.Identity + python: + - azure-mgmt-appcontainers + - azure-identity + nodejs: + - '@azure/arm-appcontainers' + - '@azure/identity' + special_considerations: + - Requires Container Apps Environment (with Log Analytics workspace) + - Requires Container Registry for images + - Ingress configuration determines public/private access + - Environment provides VNet integration (not private endpoints) + friendly_name: container-app + Microsoft.App/managedEnvironments: + display_name: Container Apps Environment + resource_provider: Microsoft.App + resource_type: Microsoft.App/managedEnvironments + api_version: '2024-03-01' + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + contributor: Contributor (scoped to app) + rbac_role_ids: {} + authentication: + method: User-Assigned Managed Identity attached to app + token_scope: null + notes: | + - Identity assigned at container app level + - Uses workload identity for outbound connections + - No private endpoint; VNet integration via environment + sdk_packages: + dotnet: + - Azure.ResourceManager.AppContainers + - Azure.Identity + python: + - azure-mgmt-appcontainers + - azure-identity + nodejs: + - '@azure/arm-appcontainers' + - '@azure/identity' + special_considerations: + - Requires Container Apps Environment (with Log Analytics workspace) + - Requires Container Registry for images + - Ingress configuration determines public/private access + - Environment provides VNet integration (not private endpoints) + friendly_name: container-app-environment + Microsoft.ContainerRegistry/registries: + display_name: Azure Container Registry + resource_provider: Microsoft.ContainerRegistry + resource_type: Microsoft.ContainerRegistry/registries + api_version: 2023-11-01-preview + private_endpoint: + dns_zone: privatelink.azurecr.io + group_id: registry + rbac_roles: + pull: AcrPull + push: AcrPush + admin: AcrImageSigner + rbac_role_ids: + pull: 7f951dda-4ed3-4680-a7ca-43fe172d538d + push: 8311e382-0749-4cb8-b61a-304f252e45ec + authentication: + method: RBAC with Managed Identity + token_scope: null + notes: | + - Admin user should be disabled + - Use AcrPull role for container runtimes + - Token-based repository-scoped access available + sdk_packages: + dotnet: + - Azure.Containers.ContainerRegistry + - Azure.Identity + python: + - azure-containerregistry + - azure-identity + nodejs: + - '@azure/container-registry' + - '@azure/identity' + special_considerations: + - Premium tier required for private endpoints and geo-replication + - Image vulnerability scanning available with Defender for Containers + friendly_name: container-registry + Microsoft.Web/sites: + display_name: Azure App Service + resource_provider: Microsoft.Web + resource_type: Microsoft.Web/sites + api_version: '2023-12-01' + private_endpoint: + dns_zone: privatelink.azurewebsites.net + group_id: sites + rbac_roles: + contributor: Website Contributor + rbac_role_ids: {} + authentication: + method: User-Assigned Managed Identity attached to web app + token_scope: null + notes: | + - Identity assigned at web app level + - Easy Auth available for end-user authentication + sdk_packages: + dotnet: + - Azure.ResourceManager.AppService + - Azure.Identity + python: + - azure-mgmt-web + - azure-identity + nodejs: + - '@azure/arm-appservice' + - '@azure/identity' + special_considerations: + - Requires App Service Plan + - Can use VNet integration for outbound + - Supports deployment slots + - Always-on setting required for production workloads + friendly_name: app-service + kind: app + Microsoft.Web/serverfarms: + display_name: App Service Plan + resource_provider: Microsoft.Web + resource_type: Microsoft.Web/serverfarms + api_version: '2023-12-01' + private_endpoint: + dns_zone: privatelink.azurewebsites.net + group_id: sites + rbac_roles: + contributor: Website Contributor + rbac_role_ids: {} + authentication: + method: User-Assigned Managed Identity attached to web app + token_scope: null + notes: | + - Identity assigned at web app level + - Easy Auth available for end-user authentication + sdk_packages: + dotnet: + - Azure.ResourceManager.AppService + - Azure.Identity + python: + - azure-mgmt-web + - azure-identity + nodejs: + - '@azure/arm-appservice' + - '@azure/identity' + special_considerations: + - Requires App Service Plan + - Can use VNet integration for outbound + - Supports deployment slots + - Always-on setting required for production workloads + friendly_name: app-service-plan + Microsoft.ApiManagement/service: + display_name: Azure API Management + resource_provider: Microsoft.ApiManagement + resource_type: Microsoft.ApiManagement/service + api_version: 2023-09-01-preview + private_endpoint: + dns_zone: privatelink.azure-api.net + group_id: Gateway + rbac_roles: + reader: API Management Service Reader + contributor: API Management Service Contributor + rbac_role_ids: {} + authentication: + method: Managed Identity for backend authentication + token_scope: null + notes: | + - Use managed identity for authenticating to backend APIs + - Configure authentication policies in APIM + - Subscription keys for consumer-facing access control + sdk_packages: + dotnet: + - Azure.ResourceManager.ApiManagement + - Azure.Identity + python: + - azure-mgmt-apimanagement + - azure-identity + nodejs: + - '@azure/arm-apimanagement' + - '@azure/identity' + special_considerations: + - Long deployment times (30-45 minutes) + - Multiple SKU tiers with different capabilities + - VNet integration modes (external/internal) + - v2 SKUs offer faster deployment and scaling + friendly_name: api-management + Microsoft.SignalRService/signalR: + display_name: Azure SignalR Service + resource_provider: Microsoft.SignalRService + resource_type: Microsoft.SignalRService/signalR + api_version: '2024-03-01' + private_endpoint: + dns_zone: privatelink.service.signalr.net + group_id: signalr + rbac_roles: + app_server: SignalR App Server + admin: SignalR Service Owner + rbac_role_ids: {} + authentication: + method: RBAC with Managed Identity + token_scope: null + notes: | + - Use AAD authentication instead of connection strings in production + - SignalR App Server role required for server-side connections + sdk_packages: + dotnet: + - Microsoft.Azure.SignalR + - Azure.Identity + python: [] + nodejs: + - '@microsoft/signalr' + - '@azure/identity' + special_considerations: + - No dedicated Python SDK; use REST API or Azure Functions bindings + - Serverless mode available for event-driven architectures + - Consider connection limits per unit + - Upstream URL configuration for serverless mode + friendly_name: signalr + Microsoft.Insights/components: + display_name: Application Insights + resource_provider: Microsoft.Insights + resource_type: Microsoft.Insights/components + api_version: '2020-02-02' + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + reader: Application Insights Component Reader + contributor: Application Insights Component Contributor + rbac_role_ids: {} + authentication: + method: Connection string or Managed Identity + token_scope: null + notes: | + - Modern SDKs support AAD authentication + - Connection string does not contain secrets (just instrumentation key) + - OpenTelemetry-based SDKs recommended for new projects + sdk_packages: + dotnet: + - Microsoft.ApplicationInsights.AspNetCore + - Azure.Monitor.OpenTelemetry.AspNetCore + python: + - opencensus-ext-azure + - azure-monitor-opentelemetry + nodejs: + - applicationinsights + - '@azure/monitor-opentelemetry' + special_considerations: + - Requires Log Analytics workspace + - Connection string safe to include in config (not a secret) + - OpenTelemetry distro is the modern recommended approach + friendly_name: app-insights + Microsoft.OperationalInsights/workspaces: + display_name: Log Analytics Workspace + resource_provider: Microsoft.OperationalInsights + resource_type: Microsoft.OperationalInsights/workspaces + api_version: '2023-09-01' + private_endpoint: + dns_zone: privatelink.oms.opinsights.azure.com + group_id: azuremonitor + rbac_roles: {} + rbac_role_ids: {} + authentication: + method: null + token_scope: https://api.loganalytics.io/.default + notes: | + - Resources send logs via diagnostic settings (references workspace ID, no RBAC needed) + - Query/management access via Log Analytics Reader (73c42c96) or Contributor (92aaf0da) + should be assigned post-deployment to user/operator identities, not application identities + sdk_packages: + dotnet: + - Azure.Monitor.Query + - Azure.Identity + python: + - azure-monitor-query + - azure-identity + nodejs: + - '@azure/monitor-query' + - '@azure/identity' + special_considerations: + - Foundation for most monitoring scenarios + - Required by App Insights, Container Apps Environment + - Consider data retention settings and cost implications + - Dedicated clusters available for high-volume scenarios + friendly_name: log-analytics + Microsoft.ContainerService/managedClusters: + display_name: Azure Kubernetes Service + resource_provider: Microsoft.ContainerService + resource_type: Microsoft.ContainerService/managedClusters + api_version: 2024-03-02-preview + private_endpoint: + dns_zone: privatelink..azmk8s.io + group_id: management + rbac_roles: + cluster_user: Azure Kubernetes Service Cluster User Role + rbac_admin: Azure Kubernetes Service RBAC Admin + rbac_writer: Azure Kubernetes Service RBAC Writer + rbac_reader: Azure Kubernetes Service RBAC Reader + rbac_role_ids: + cluster_user: 4abbcc35-e782-43d8-92c5-2d3f1bd2253f + rbac_admin: 3498e952-d568-435e-9b2c-8d77e338d7f7 + rbac_writer: a7ffa36f-339b-4b5c-8bdf-e2c188b2c0eb + rbac_reader: 7f6c6a51-bcf8-42ba-9220-52d62157d06d + authentication: + method: Azure AD + Kubernetes RBAC with Workload Identity + token_scope: 6dae42f8-4368-4678-94ff-3960e28e3630/.default + notes: | + - Workload identity for pod-level Azure service access + - OIDC issuer must be enabled on cluster + - Federated identity credentials link K8s service accounts to Azure identities + sdk_packages: + dotnet: + - Azure.ResourceManager.ContainerService + - Azure.Identity + python: + - azure-mgmt-containerservice + - azure-identity + nodejs: + - '@azure/arm-containerservice' + - '@azure/identity' + special_considerations: + - Network plugin choice (Azure CNI vs kubenet) is permanent + - System node pool minimum VM size is Standard_B2s + - AcrPull role must be on kubelet identity, not cluster identity + - Private cluster requires VPN/bastion for API server access + friendly_name: aks + Microsoft.Compute/virtualMachines: + display_name: Azure Virtual Machines + resource_provider: Microsoft.Compute + resource_type: Microsoft.Compute/virtualMachines + api_version: '2024-03-01' + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + contributor: Virtual Machine Contributor + admin_login: Virtual Machine Administrator Login + user_login: Virtual Machine User Login + rbac_role_ids: + contributor: 9980e02c-c2be-4d73-94e8-173b1dc7cf3c + admin_login: 1c0163c0-47e6-4577-8991-ea5c82e286e4 + user_login: fb879df8-f326-4884-b1cf-06f3ad86be52 + authentication: + method: SSH key (Linux) or password (Windows) + Azure AD login + token_scope: null + notes: | + - Always use SSH keys for Linux (never passwords) + - Managed identity for Azure service access from VM + - Azure AD login available as alternative to local accounts + sdk_packages: + dotnet: + - Azure.ResourceManager.Compute + - Azure.Identity + python: + - azure-mgmt-compute + - azure-identity + nodejs: + - '@azure/arm-compute' + - '@azure/identity' + special_considerations: + - VMs are IaaS -- require OS patching and security hardening + - Always configure auto-shutdown for non-production + - Use Azure Bastion instead of public IPs for management + - Windows VM names limited to 15 characters + friendly_name: virtual-machines + Microsoft.Web/staticSites: + display_name: Azure Static Web Apps + resource_provider: Microsoft.Web + resource_type: Microsoft.Web/staticSites + api_version: '2023-12-01' + private_endpoint: + dns_zone: privatelink.azurestaticapps.net + group_id: staticSites + rbac_roles: + contributor: Website Contributor + rbac_role_ids: {} + authentication: + method: Deployment token (API key) for CI/CD + token_scope: null + notes: | + - Built-in auth providers (GitHub, Azure AD, Twitter) + - Custom auth available on Standard tier + - API key used for deployment, not data access + sdk_packages: + dotnet: + - Azure.ResourceManager.AppService + - Azure.Identity + python: + - azure-mgmt-web + - azure-identity + nodejs: + - '@azure/arm-appservice' + - '@azure/identity' + special_considerations: + - Free tier has no SLA + - Managed Functions only support Node.js and Python + - All API routes must start with /api/ + - Standard tier required for private endpoints and linked backends + friendly_name: static-web-apps + Microsoft.Cdn/profiles: + display_name: Azure Front Door + resource_provider: Microsoft.Cdn + resource_type: Microsoft.Cdn/profiles + api_version: '2024-02-01' + private_endpoint: + dns_zone: null + group_id: null + rbac_roles: + contributor: CDN Profile Contributor + reader: CDN Profile Reader + rbac_role_ids: {} + authentication: + method: null + token_scope: null + notes: | + - Front Door is a reverse proxy; no data-plane auth + - WAF policies for request filtering (Premium tier) + - Private Link origins for secure backend connectivity (Premium tier) + sdk_packages: + dotnet: + - Azure.ResourceManager.Cdn + - Azure.Identity + python: + - azure-mgmt-cdn + - azure-identity + nodejs: + - '@azure/arm-cdn' + - '@azure/identity' + special_considerations: + - Standard = CDN + routing; Premium = WAF + Private Link origins + - Profile changes take 10-20 minutes to propagate globally + - WAF policy names cannot contain hyphens + - DNS CNAME validation required for custom domains + friendly_name: front-door + Microsoft.DBforPostgreSQL/flexibleServers: + display_name: Azure Database for PostgreSQL (Flexible Server) + resource_provider: Microsoft.DBforPostgreSQL + resource_type: Microsoft.DBforPostgreSQL/flexibleServers + api_version: 2023-12-01-preview + private_endpoint: + dns_zone: privatelink.postgres.database.azure.com + group_id: postgresqlServer + rbac_roles: + data_read: db_datareader (contained user) + data_write: db_datawriter (contained user) + admin: azure_pg_admin (server role) + rbac_role_ids: {} + authentication: + method: Azure AD with Managed Identity + password for admin + token_scope: https://ossrdbms-aad.database.windows.net/.default + notes: | + - AAD auth enabled alongside password auth + - Managed identity creates AAD database roles via SQL + - Token refresh needed for long connections (~1 hour expiry) + sdk_packages: + dotnet: + - Npgsql + - Azure.Identity + python: + - psycopg2-binary + - azure-identity + nodejs: + - pg + - '@azure/identity' + special_considerations: + - VNet integration (delegated subnet) is set at creation time + - AAD role creation requires AAD admin to run SQL commands post-deployment + - pgvector extension must be explicitly enabled + - Burstable tier has limited IOPS + friendly_name: postgresql + Microsoft.Search/searchServices: + display_name: Azure AI Search + resource_provider: Microsoft.Search + resource_type: Microsoft.Search/searchServices + api_version: 2024-03-01-preview + private_endpoint: + dns_zone: privatelink.search.windows.net + group_id: searchService + rbac_roles: + data_read: Search Index Data Reader + data_write: Search Index Data Contributor + admin: Search Service Contributor + rbac_role_ids: + data_read: 1407120a-92aa-4202-b7e9-c0e197c71c8f + data_write: 8ebe5a00-799e-43f5-93ac-243d3dce84a7 + admin: 7ca78c08-252a-4471-8644-bb5ff32d4ba0 + authentication: + method: RBAC with Managed Identity or API key + token_scope: https://search.azure.com/.default + notes: | + - RBAC preferred over API keys for production + - Set disableLocalAuth=true when RBAC fully configured + - Supports both data-plane and control-plane RBAC + sdk_packages: + dotnet: + - Azure.Search.Documents + - Azure.Identity + python: + - azure-search-documents + - azure-identity + nodejs: + - '@azure/search-documents' + - '@azure/identity' + special_considerations: + - Index schema changes may require full reindex + - Semantic ranker free tier limited to 1000 queries/month + - Vector dimensions must match embedding model + - Integrated vectorization is preview; push model more mature + friendly_name: azure-ai-search + Microsoft.Databricks/workspaces: + display_name: Azure Databricks + resource_provider: Microsoft.Databricks + resource_type: Microsoft.Databricks/workspaces + api_version: '2024-05-01' + private_endpoint: + dns_zone: privatelink.azuredatabricks.net + group_id: databricks_ui_api + rbac_roles: + contributor: Contributor (scoped to workspace) + rbac_role_ids: {} + authentication: + method: Azure AD for workspace access; Unity Catalog for data + token_scope: 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default + notes: | + - Workspace access via Azure AD SSO + - Data access via Unity Catalog grants (not ARM RBAC) + - Databricks secret scopes for credential management + sdk_packages: + dotnet: + - Azure.ResourceManager.Databricks + - Azure.Identity + python: + - databricks-sdk + - azure-identity + nodejs: + - '@azure/arm-databricks' + - '@azure/identity' + special_considerations: + - Premium tier required for Unity Catalog, RBAC, audit logs + - VNet injection subnet sizing critical (/26 minimum) + - DBU pricing varies by workload type (Jobs < All-Purpose) + - Managed resource group must not already exist + friendly_name: databricks + Microsoft.DataFactory/factories: + display_name: Azure Data Factory + resource_provider: Microsoft.DataFactory + resource_type: Microsoft.DataFactory/factories + api_version: '2018-06-01' + private_endpoint: + dns_zone: privatelink.datafactory.azure.net + group_id: dataFactory + rbac_roles: + contributor: Data Factory Contributor + rbac_role_ids: + contributor: 673868aa-7521-48a0-acc6-0f60742d39f5 + authentication: + method: Managed Identity for data source connections + token_scope: null + notes: | + - ADF managed identity authenticates to data sources + - Grant identity RBAC roles on each connected resource + - Self-hosted IR for on-premises data sources + sdk_packages: + dotnet: + - Azure.ResourceManager.DataFactory + - Azure.Identity + python: + - azure-mgmt-datafactory + - azure-identity + nodejs: + - '@azure/arm-datafactory' + - '@azure/identity' + special_considerations: + - Self-hosted integration runtime needed for on-premises + - Mapping data flow has 3-5 minute cold start + - Pipeline JSON ordering causes Terraform plan drift + - Schedule triggers default to UTC timezone + friendly_name: data-factory + Microsoft.Fabric/capacities: + display_name: Microsoft Fabric + resource_provider: Microsoft.Fabric + resource_type: Microsoft.Fabric/capacities + api_version: '2023-11-01' + private_endpoint: + dns_zone: null + group_id: fabric + rbac_roles: + contributor: Contributor (scoped to capacity) + rbac_role_ids: {} + authentication: + method: Azure AD for Fabric portal; workspace roles for data + token_scope: https://api.fabric.microsoft.com/.default + notes: | + - Capacity is ARM-deployed; workspaces are Fabric-managed + - Workspace roles (Admin/Member/Contributor/Viewer) via Fabric API + - OneLake access governed by workspace permissions + sdk_packages: + dotnet: + - Azure.ResourceManager.Fabric + - Azure.Identity + python: + - azure-mgmt-fabric + - azure-identity + nodejs: + - '@azure/arm-fabric' + - '@azure/identity' + special_considerations: + - Capacity vs workspace distinction (ARM vs SaaS) + - F2 is smallest capacity SKU (~$0.36/hr) + - 60-day free trial available per tenant + - No VNet injection; use managed private endpoints + - Workspaces cannot be created via Terraform/Bicep + friendly_name: fabric + Microsoft.Insights/diagnosticSettings: + display_name: Diagnostic Settings + resource_provider: Microsoft.Insights + resource_type: Microsoft.Insights/diagnosticSettings + api_version: 2021-05-01-preview + notes: | + - Extension resource — does NOT support tags + - API version @2021-05-01-preview required for categoryGroup ("allLogs") support + - Older @2016-09-01 only supports individual category names, NOT categoryGroup + - NSGs do NOT support diagnostic settings (no log or metric categories) + - VNets support ONLY AllMetrics, NOT log categories + friendly_name: diagnostic-settings + Microsoft.Authorization/roleAssignments: + display_name: Role Assignments + resource_provider: Microsoft.Authorization + resource_type: Microsoft.Authorization/roleAssignments + api_version: '2022-04-01' + notes: | + - Extension resource — does NOT support tags + - Use deterministic names via uuidv5() for idempotent plans + - Scope to the narrowest resource, not resource group or subscription + friendly_name: role-assignments + Microsoft.Web/sites#functionapp: + display_name: Azure Functions + resource_provider: Microsoft.Web + resource_type: Microsoft.Web/sites + api_version: '2023-12-01' + private_endpoint: + dns_zone: privatelink.azurewebsites.net + group_id: sites + rbac_roles: + contributor: Website Contributor + rbac_role_ids: {} + authentication: + method: User-Assigned Managed Identity attached to function app + token_scope: null + notes: | + - Identity assigned at function app level + - Use managed identity for connections to other Azure services + sdk_packages: + dotnet: + - Microsoft.Azure.Functions.Worker + - Azure.Identity + python: + - azure-functions + - azure-identity + nodejs: + - '@azure/functions' + - '@azure/identity' + special_considerations: + - Requires App Service Plan or Consumption plan + - Requires Storage Account for runtime + - Can use VNet integration for outbound + - Flex Consumption plan offers per-function scaling + friendly_name: azure-functions + kind: functionapp diff --git a/azext_prototype/knowledge/services/action-groups.md b/azext_prototype/knowledge/services/action-groups.md new file mode 100644 index 0000000..4e716f9 --- /dev/null +++ b/azext_prototype/knowledge/services/action-groups.md @@ -0,0 +1,214 @@ +--- +service_namespace: Microsoft.Insights/actionGroups +display_name: Azure Monitor Action Groups +--- + +# Azure Monitor Action Groups +> Reusable notification and automation targets for Azure Monitor alerts, enabling email, SMS, webhook, Logic App, Azure Function, and ITSM integrations when alerts fire. + +## When to Use + +- Defining notification targets (email, SMS, push) for Azure Monitor alert rules +- Triggering automated remediation via Azure Functions, Logic Apps, or webhooks on alert +- Centralizing alert routing so multiple alert rules share the same notification configuration +- ITSM integration for incident creation in ServiceNow, PagerDuty, etc. +- NOT suitable for: complex event processing (use Event Grid or Logic Apps), data ingestion (use Event Hubs), or scheduled tasks (use Azure Automation) + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Email receivers | 1-2 team emails | Sufficient for POC alerting | +| SMS receivers | None | Add for production on-call | +| Short name | 12 chars max | Required; displayed in notifications | +| Enabled | true | Action group must be enabled to fire | +| ARM role receivers | None | Use for production to notify by Azure role | + +**Foundation service**: Action Groups are typically created alongside the monitoring stack (Log Analytics, App Insights) and referenced by all alert rules across the deployment. + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "action_group" { + type = "Microsoft.Insights/actionGroups@2023-09-01-preview" + name = var.name + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + groupShortName = var.short_name # Max 12 characters + enabled = true + emailReceivers = [ + { + name = "team-email" + emailAddress = var.email_address + useCommonAlertSchema = true + } + ] + } + } + + tags = var.tags +} +``` + +### With Webhook Receiver + +```hcl +resource "azapi_resource" "action_group_webhook" { + type = "Microsoft.Insights/actionGroups@2023-09-01-preview" + name = var.name + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + groupShortName = var.short_name + enabled = true + emailReceivers = [ + { + name = "team-email" + emailAddress = var.email_address + useCommonAlertSchema = true + } + ] + webhookReceivers = [ + { + name = "ops-webhook" + serviceUri = var.webhook_uri + useCommonAlertSchema = true + useAadAuth = true + objectId = var.webhook_aad_object_id + tenantId = var.tenant_id + } + ] + } + } + + tags = var.tags +} +``` + +### With Azure Function Receiver + +```hcl +resource "azapi_resource" "action_group_function" { + type = "Microsoft.Insights/actionGroups@2023-09-01-preview" + name = var.name + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + groupShortName = var.short_name + enabled = true + azureFunctionReceivers = [ + { + name = "remediation-function" + functionAppResourceId = var.function_app_id + functionName = var.function_name + httpTriggerUrl = var.function_trigger_url + useCommonAlertSchema = true + } + ] + } + } + + tags = var.tags +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param shortName string +param emailAddress string +param tags object = {} + +resource actionGroup 'Microsoft.Insights/actionGroups@2023-09-01-preview' = { + name: name + location: 'global' + tags: tags + properties: { + groupShortName: shortName + enabled: true + emailReceivers: [ + { + name: 'team-email' + emailAddress: emailAddress + useCommonAlertSchema: true + } + ] + } +} + +output id string = actionGroup.id +output name string = actionGroup.name +``` + +### With Webhook Receiver + +```bicep +param name string +param shortName string +param emailAddress string +param webhookUri string +param tags object = {} + +resource actionGroup 'Microsoft.Insights/actionGroups@2023-09-01-preview' = { + name: name + location: 'global' + tags: tags + properties: { + groupShortName: shortName + enabled: true + emailReceivers: [ + { + name: 'team-email' + emailAddress: emailAddress + useCommonAlertSchema: true + } + ] + webhookReceivers: [ + { + name: 'ops-webhook' + serviceUri: webhookUri + useCommonAlertSchema: true + } + ] + } +} + +output id string = actionGroup.id +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Short name exceeds 12 characters | Deployment fails with validation error | Keep `groupShortName` to 12 characters or fewer | +| Not enabling common alert schema | Inconsistent payload formats across alert types | Set `useCommonAlertSchema = true` on all receivers | +| Too many email receivers | Alert fatigue, emails ignored | Use 1-2 emails for POC; use ARM role receivers for production | +| Forgetting to link action group to alert rules | Action group exists but never fires | Always reference the action group ID in metric/log alert rules | +| Not testing action group | Notifications may fail silently (bad email, expired webhook) | Use the "Test" feature in the portal after deployment | +| Using HTTP webhook without AAD auth | Webhook endpoint exposed to unauthenticated callers | Enable `useAadAuth` on webhook receivers in production | +| Location not set to "global" | Deployment may fail or behave unexpectedly | Action Groups are global resources; always use `location = "global"` | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| SMS/voice receivers | P3 | Add SMS and voice call receivers for on-call escalation | +| ARM role receivers | P2 | Notify by Azure AD role (e.g., Owner, Contributor) instead of individual emails | +| Logic App integration | P3 | Connect to Logic Apps for complex notification workflows (Teams, Slack) | +| ITSM connector | P2 | Integrate with ServiceNow/PagerDuty for automated incident creation | +| Rate limiting awareness | P3 | Document and plan around action group rate limits (max 1 SMS/voice per 5 min per number) | +| Suppression rules | P3 | Configure alert processing rules to suppress notifications during maintenance windows | +| Secure webhook with AAD | P1 | Enable AAD authentication on all webhook receivers | +| Multiple action groups | P3 | Create separate action groups for severity levels (critical vs. warning) | diff --git a/azext_prototype/knowledge/services/aks-agent-pool.md b/azext_prototype/knowledge/services/aks-agent-pool.md new file mode 100644 index 0000000..4d68605 --- /dev/null +++ b/azext_prototype/knowledge/services/aks-agent-pool.md @@ -0,0 +1,146 @@ +--- +service_namespace: Microsoft.ContainerService/managedClusters/agentPools +display_name: AKS Agent Pool +depends_on: + - Microsoft.ContainerService/managedClusters +--- + +# AKS Agent Pool + +> Additional node pool in an AKS cluster, enabling workload isolation through separate VM sizes, scaling rules, OS types, and node labels/taints. + +## When to Use +- **Workload isolation** -- separate system pods from application workloads on dedicated node pools +- **GPU workloads** -- add GPU-enabled VMs (NC/ND series) for ML inference or training +- **Windows containers** -- add Windows node pools alongside Linux system pool +- **Spot instances** -- cost savings for interruptible batch or dev/test workloads +- **Mixed VM sizes** -- different CPU/memory ratios for varied workload profiles (e.g., memory-intensive vs CPU-intensive) + +Every AKS cluster has at least one System node pool. User node pools are added for application workloads. The System pool runs critical add-ons (CoreDNS, kube-proxy, metrics-server). + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Mode | User | System pool created with cluster; add User pools for workloads | +| VM size | Standard_D2s_v5 | 2 vCPU, 8 GiB; general-purpose for POC | +| Node count | 1 | Fixed for POC; enable autoscaler for production | +| OS type | Linux | Default; Windows for .NET Framework workloads | +| OS disk size | 50 GB | Ephemeral OS disk if VM supports it | +| Max pods per node | 110 | Azure CNI default; 250 max | +| Autoscaler | Disabled for POC | Enable with min/max for production | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "user_pool" { + type = "Microsoft.ContainerService/managedClusters/agentPools@2024-03-02-preview" + name = "workload" + parent_id = azapi_resource.aks_cluster.id + + body = { + properties = { + vmSize = "Standard_D2s_v5" + count = 1 + minCount = 1 + maxCount = 5 + enableAutoScaling = false # Enable for production + osDiskSizeGB = 50 + osDiskType = "Managed" # or "Ephemeral" for supported VMs + mode = "User" + osType = "Linux" + osSKU = "Ubuntu" # or "AzureLinux" + maxPods = 110 + nodeLabels = { + "workload-type" = "app" + } + upgradeSettings = { + maxSurge = "10%" + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# Agent pools inherit RBAC from the parent AKS cluster. +# No additional role assignments are needed at the pool level. +# Use Azure Kubernetes Service Cluster Admin (0ab0b1a8-8aac-4efd-b8c2-3ee1fb270be8) +# or Contributor on the cluster for node pool management. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the agent pool (max 12 chars, lowercase, no hyphens)') +param poolName string + +@description('VM size for the pool nodes') +param vmSize string = 'Standard_D2s_v5' + +@description('Number of nodes') +param nodeCount int = 1 + +resource agentPool 'Microsoft.ContainerService/managedClusters/agentPools@2024-03-02-preview' = { + parent: aksCluster + name: poolName + properties: { + vmSize: vmSize + count: nodeCount + minCount: 1 + maxCount: 5 + enableAutoScaling: false + osDiskSizeGB: 50 + osDiskType: 'Managed' + mode: 'User' + osType: 'Linux' + osSKU: 'Ubuntu' + maxPods: 110 + nodeLabels: { + 'workload-type': 'app' + } + upgradeSettings: { + maxSurge: '10%' + } + } +} +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Node pools are a scheduling concern; applications target pools via node selectors and tolerations in Kubernetes manifests. + +### C# +Infrastructure -- transparent to application code. Node pools are a scheduling concern; applications target pools via node selectors and tolerations in Kubernetes manifests. + +### Node.js +Infrastructure -- transparent to application code. Node pools are a scheduling concern; applications target pools via node selectors and tolerations in Kubernetes manifests. + +## Common Pitfalls + +1. **Pool name constraints** -- Names must be lowercase alphanumeric, max 12 characters for Linux (6 for Windows). No hyphens, underscores, or uppercase letters. Deployment fails with a cryptic error otherwise. +2. **Cannot change VM size after creation** -- VM size is immutable on an existing pool. To change, create a new pool, cordon/drain the old one, and delete it. +3. **System pool cannot be deleted** -- A cluster must always have at least one System mode pool. Convert another pool to System before deleting the original. +4. **Spot pool eviction** -- Spot node pools can be evicted at any time. Only use for fault-tolerant workloads (batch, CI, dev/test). Never run stateful or production workloads on spot pools. +5. **Ephemeral OS disk size** -- If using `Ephemeral` OS disk type, the VM's cache or temp disk must be large enough for the OS disk. Otherwise, pool creation fails silently. +6. **Max pods per node vs subnet sizing** -- With Azure CNI, each pod gets a VNet IP. Setting `maxPods: 110` on a large pool can exhaust the subnet. Use CNI Overlay to avoid this. +7. **Node labels vs taints** -- Labels are for affinity; taints are for repulsion. Forgetting to add tolerations for custom taints causes pods to remain Pending indefinitely. +8. **Availability zone mismatch** -- If the cluster has zone-redundant system pool but user pool is in a single zone, pod scheduling may fail during a zone outage. + +## Production Backlog Items + +- [ ] Enable cluster autoscaler with appropriate min/max node counts +- [ ] Configure availability zones for zone-redundant node pools +- [ ] Add node taints for workload isolation (e.g., GPU, Windows) +- [ ] Switch to ephemeral OS disks for faster node scaling +- [ ] Implement pod disruption budgets for graceful upgrades +- [ ] Configure node pool auto-upgrade channel aligned with cluster +- [ ] Add dedicated system node pool with appropriate sizing for add-ons +- [ ] Evaluate AzureLinux OS SKU for reduced attack surface and faster boot diff --git a/azext_prototype/knowledge/services/aks.md b/azext_prototype/knowledge/services/aks.md index 2b90439..b459c79 100644 --- a/azext_prototype/knowledge/services/aks.md +++ b/azext_prototype/knowledge/services/aks.md @@ -1,356 +1,416 @@ -# Azure Kubernetes Service (AKS) -> Managed Kubernetes cluster for deploying, scaling, and operating containerized applications with enterprise-grade security and governance. - -## When to Use - -- **Microservices at scale** -- multiple services with independent scaling, deployment, and lifecycle management -- **Existing Kubernetes expertise** -- teams already invested in Kubernetes tooling (Helm, Kustomize, ArgoCD) -- **Complex networking requirements** -- service mesh, network policies, ingress controllers with fine-grained control -- **Hybrid / multi-cloud portability** -- workloads that may need to run on other Kubernetes platforms -- **Stateful workloads** -- databases, message queues, or ML training that need persistent volumes - -Choose AKS over Container Apps when you need full Kubernetes control, custom operators, service mesh, or have existing Kubernetes manifests. Choose Container Apps for simpler containerized apps where Kubernetes complexity isn't needed. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | Free | No SLA; sufficient for POC | -| Node pool VM | Standard_B2s | 2 vCPU, 4 GiB; lowest practical for POC | -| Node count | 1-2 | Minimum; use auto-scaler for production | -| Kubernetes version | Latest stable | e.g., 1.29.x | -| Network plugin | Azure CNI Overlay | Simplest; avoids subnet sizing complexity | -| RBAC | Azure AD + Kubernetes RBAC | Integrated by default | -| Managed identity | System-assigned | For cluster operations | -| Workload identity | Enabled | For pod-level Azure service access | -| Container Registry | ACR with AcrPull | Managed identity-based image pulling | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_kubernetes_cluster" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - dns_prefix = var.dns_prefix - kubernetes_version = var.kubernetes_version # e.g., "1.29" - sku_tier = "Free" # "Standard" for SLA - - default_node_pool { - name = "system" - node_count = 1 - vm_size = "Standard_B2s" - os_disk_size_gb = 30 - temporary_name_for_rotation = "systemtemp" - - upgrade_settings { - max_surge = "10%" - } - } - - identity { - type = "SystemAssigned" - } - - network_profile { - network_plugin = "azure" - network_policy = "azure" # or "calico" for more features - network_data_plane = "cilium" # Azure CNI Overlay with Cilium - service_cidr = "10.0.0.0/16" - dns_service_ip = "10.0.0.10" - } - - oidc_issuer_enabled = true # Required for workload identity - workload_identity_enabled = true # Pod-level Azure AD auth - - azure_active_directory_role_based_access_control { - azure_rbac_enabled = true - managed = true - admin_group_object_ids = var.admin_group_ids - } - - tags = var.tags -} -``` - -### User Node Pool - -```hcl -resource "azurerm_kubernetes_cluster_node_pool" "workload" { - name = "workload" - kubernetes_cluster_id = azurerm_kubernetes_cluster.this.id - vm_size = "Standard_D2s_v5" - node_count = 1 - min_count = 1 - max_count = 5 - enable_auto_scaling = true - os_disk_size_gb = 50 - - node_labels = { - "workload" = "app" - } - - tags = var.tags -} -``` - -### RBAC Assignment - -```hcl -# AcrPull -- allow AKS to pull images from ACR -resource "azurerm_role_assignment" "acr_pull" { - scope = var.container_registry_id - role_definition_name = "AcrPull" - principal_id = azurerm_kubernetes_cluster.this.kubelet_identity[0].object_id -} - -# Azure Kubernetes Service Cluster User Role -- allows kubectl access -resource "azurerm_role_assignment" "cluster_user" { - scope = azurerm_kubernetes_cluster.this.id - role_definition_name = "Azure Kubernetes Service Cluster User Role" - principal_id = var.developer_group_principal_id -} - -# Azure Kubernetes Service RBAC Writer -- namespace-scoped write access -resource "azurerm_role_assignment" "rbac_writer" { - scope = azurerm_kubernetes_cluster.this.id - role_definition_name = "Azure Kubernetes Service RBAC Writer" - principal_id = var.developer_group_principal_id -} -``` - -RBAC role IDs: -- Azure Kubernetes Service Cluster User Role: `4abbcc35-e782-43d8-92c5-2d3f1bd2253f` -- Azure Kubernetes Service RBAC Admin: `3498e952-d568-435e-9b2c-8d77e338d7f7` -- Azure Kubernetes Service RBAC Writer: `a7ffa36f-339b-4b5c-8bdf-e2c188b2c0eb` -- Azure Kubernetes Service RBAC Reader: `7f6c6a51-bcf8-42ba-9220-52d62157d06d` - -### Private Endpoint - -AKS uses **private cluster** mode rather than traditional private endpoints: - -```hcl -resource "azurerm_kubernetes_cluster" "this" { - # ... (same as basic, plus:) - private_cluster_enabled = true - private_dns_zone_id = "System" # or custom zone ID - private_cluster_public_fqdn_enabled = false -} -``` - -Private DNS zone: `privatelink..azmk8s.io` - -**Note:** Private clusters require VPN, ExpressRoute, or a jump box to access the API server. For POC, keep public API server access enabled. - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the AKS cluster') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('DNS prefix for the cluster') -param dnsPrefix string - -@description('Kubernetes version') -param kubernetesVersion string = '1.29' - -@description('Admin group object IDs for cluster admin access') -param adminGroupObjectIds array = [] - -@description('Tags to apply') -param tags object = {} - -resource aks 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { - name: name - location: location - tags: tags - sku: { - name: 'Base' - tier: 'Free' - } - identity: { - type: 'SystemAssigned' - } - properties: { - kubernetesVersion: kubernetesVersion - dnsPrefix: dnsPrefix - agentPoolProfiles: [ - { - name: 'system' - count: 1 - vmSize: 'Standard_B2s' - osDiskSizeGB: 30 - mode: 'System' - osType: 'Linux' - } - ] - networkProfile: { - networkPlugin: 'azure' - networkPolicy: 'azure' - serviceCidr: '10.0.0.0/16' - dnsServiceIP: '10.0.0.10' - } - oidcIssuerProfile: { - enabled: true - } - securityProfile: { - workloadIdentity: { - enabled: true - } - } - aadProfile: { - managed: true - enableAzureRBAC: true - adminGroupObjectIDs: adminGroupObjectIds - } - } -} - -output id string = aks.id -output name string = aks.name -output fqdn string = aks.properties.fqdn -output kubeletIdentityObjectId string = aks.properties.identityProfile.kubeletidentity.objectId -``` - -### RBAC Assignment - -```bicep -@description('ACR resource ID for AcrPull') -param acrId string - -// AcrPull role for kubelet identity -var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d' - -resource acrPullAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(acrId, aks.properties.identityProfile.kubeletidentity.objectId, acrPullRoleId) - scope: resourceId('Microsoft.ContainerRegistry/registries', split(acrId, '/')[8]) - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId) - principalId: aks.properties.identityProfile.kubeletidentity.objectId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -AKS application code is standard Kubernetes -- Docker containers deployed via manifests, Helm charts, or Kustomize. - -### Kubernetes Deployment with Workload Identity - -```yaml -# deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: myapp -spec: - replicas: 2 - selector: - matchLabels: - app: myapp - template: - metadata: - labels: - app: myapp - azure.workload.identity/use: "true" # Enable workload identity - spec: - serviceAccountName: myapp-sa # Linked to Azure managed identity - containers: - - name: myapp - image: myregistry.azurecr.io/myapp:latest - ports: - - containerPort: 8080 - env: - - name: AZURE_CLIENT_ID - value: "" # From federated credential - resources: - requests: - cpu: 100m - memory: 128Mi - limits: - cpu: 500m - memory: 256Mi ---- -apiVersion: v1 -kind: Service -metadata: - name: myapp -spec: - type: ClusterIP - selector: - app: myapp - ports: - - port: 80 - targetPort: 8080 -``` - -### Workload Identity Service Account - -```yaml -# service-account.yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: myapp-sa - annotations: - azure.workload.identity/client-id: "" -``` - -### Federated Credential (Terraform) - -```hcl -resource "azurerm_federated_identity_credential" "this" { - name = "aks-${var.namespace}-${var.service_account_name}" - resource_group_name = var.resource_group_name - parent_id = var.managed_identity_id - audience = ["api://AzureADTokenExchange"] - issuer = azurerm_kubernetes_cluster.this.oidc_issuer_url - subject = "system:serviceaccount:${var.namespace}:${var.service_account_name}" -} -``` - -### Application Code with DefaultAzureCredential - -```python -# Application code is the same as any Azure SDK code -# Workload identity provides the token automatically -from azure.identity import DefaultAzureCredential -from azure.storage.blob import BlobServiceClient - -credential = DefaultAzureCredential() # Picks up workload identity in AKS -client = BlobServiceClient(account_url="https://mystorageaccount.blob.core.windows.net", credential=credential) -``` - -## Common Pitfalls - -1. **System node pool VM size too small** -- `Standard_B2s` works for POC but system pods (CoreDNS, kube-proxy, etc.) need ~500Mi memory. Don't go below B2s. -2. **Forgetting AcrPull role on kubelet identity** -- Without this, pods fail to pull images with `ImagePullBackOff`. Must assign the role to `kubelet_identity`, not the cluster identity. -3. **Network plugin choice is permanent** -- Cannot change from `kubelet` to `azure` or vice versa after cluster creation. Azure CNI Overlay is the recommended default. -4. **Workload identity requires OIDC issuer** -- Must enable `oidc_issuer_enabled` on the cluster AND create a `FederatedIdentityCredential` linking the Kubernetes service account to the Azure managed identity. -5. **Private cluster API server access** -- With `private_cluster_enabled = true`, `kubectl` commands fail unless you're on the VNet (VPN, bastion, or runner VM). For POC, keep API server public. -6. **Node pool naming constraints** -- Pool names must be lowercase, max 12 characters for Linux, 6 for Windows. No hyphens or underscores. -7. **Kubernetes version upgrades** -- AKS enforces version currency. Clusters on N-2 versions are auto-upgraded. Plan upgrade cadence. -8. **Ingress controller not included** -- AKS doesn't install an ingress controller by default. Deploy NGINX Ingress Controller or use the managed `app-routing` add-on. - -## Production Backlog Items - -- [ ] Upgrade to Standard tier for SLA (99.95% with availability zones) -- [ ] Enable availability zones on node pools -- [ ] Configure cluster auto-scaler with appropriate min/max -- [ ] Enable private cluster mode for API server -- [ ] Deploy network policies for namespace isolation -- [ ] Install and configure ingress controller (NGINX or app-routing add-on) -- [ ] Set up monitoring with Container Insights and Prometheus -- [ ] Configure Azure Policy for Kubernetes (pod security standards) -- [ ] Implement GitOps with Flux or ArgoCD for declarative deployments -- [ ] Configure node pool auto-upgrade channel -- [ ] Add separate user node pool for workloads -- [ ] Enable Defender for Containers for runtime threat protection +--- +service_namespace: Microsoft.ContainerService/managedClusters +display_name: Azure Kubernetes Service +--- + +# Azure Kubernetes Service (AKS) +> Managed Kubernetes cluster for deploying, scaling, and operating containerized applications with enterprise-grade security and governance. + +## When to Use + +- **Microservices at scale** -- multiple services with independent scaling, deployment, and lifecycle management +- **Existing Kubernetes expertise** -- teams already invested in Kubernetes tooling (Helm, Kustomize, ArgoCD) +- **Complex networking requirements** -- service mesh, network policies, ingress controllers with fine-grained control +- **Hybrid / multi-cloud portability** -- workloads that may need to run on other Kubernetes platforms +- **Stateful workloads** -- databases, message queues, or ML training that need persistent volumes + +Choose AKS over Container Apps when you need full Kubernetes control, custom operators, service mesh, or have existing Kubernetes manifests. Choose Container Apps for simpler containerized apps where Kubernetes complexity isn't needed. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Free | No SLA; sufficient for POC | +| Node pool VM | Standard_B2s | 2 vCPU, 4 GiB; lowest practical for POC | +| Node count | 1-2 | Minimum; use auto-scaler for production | +| Kubernetes version | Latest stable | e.g., 1.29.x | +| Network plugin | Azure CNI Overlay | Simplest; avoids subnet sizing complexity | +| RBAC | Azure AD + Kubernetes RBAC | Integrated by default | +| Managed identity | System-assigned | For cluster operations | +| Workload identity | Enabled | For pod-level Azure service access | +| Container Registry | ACR with AcrPull | Managed identity-based image pulling | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.ContainerService/managedClusters@2024-03-02-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Base" + tier = "Free" # "Standard" for SLA + } + properties = { + kubernetesVersion = var.kubernetes_version # e.g., "1.29" + dnsPrefix = var.dns_prefix + agentPoolProfiles = [ + { + name = "system" + count = 1 + vmSize = "Standard_B2s" + osDiskSizeGB = 30 + mode = "System" + osType = "Linux" + upgradeSettings = { + maxSurge = "10%" + } + } + ] + networkProfile = { + networkPlugin = "azure" + networkPolicy = "azure" # or "calico" for more features + networkDataplane = "cilium" # Azure CNI Overlay with Cilium + serviceCidr = "10.0.0.0/16" + dnsServiceIP = "10.0.0.10" + } + oidcIssuerProfile = { + enabled = true # Required for workload identity + } + securityProfile = { + workloadIdentity = { + enabled = true # Pod-level Azure AD auth + } + } + aadProfile = { + managed = true + enableAzureRBAC = true + adminGroupObjectIDs = var.admin_group_ids + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### User Node Pool + +```hcl +resource "azapi_resource" "workload_pool" { + type = "Microsoft.ContainerService/managedClusters/agentPools@2024-03-02-preview" + name = "workload" + parent_id = azapi_resource.this.id + + body = { + properties = { + vmSize = "Standard_D2s_v5" + count = 1 + minCount = 1 + maxCount = 5 + enableAutoScaling = true + osDiskSizeGB = 50 + mode = "User" + osType = "Linux" + nodeLabels = { + "workload" = "app" + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# AcrPull -- allow AKS to pull images from ACR +resource "azapi_resource" "acr_pull" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.container_registry_id}-acr-pull") + parent_id = var.container_registry_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" + principalId = azapi_resource.this.output.properties.identityProfile.kubeletidentity.objectId + } + } +} + +# Azure Kubernetes Service Cluster User Role -- allows kubectl access +resource "azapi_resource" "cluster_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-cluster-user") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4abbcc35-e782-43d8-92c5-2d3f1bd2253f" + principalId = var.developer_group_principal_id + } + } +} + +# Azure Kubernetes Service RBAC Writer -- namespace-scoped write access +resource "azapi_resource" "rbac_writer" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-rbac-writer") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/a7ffa36f-339b-4b5c-8bdf-e2c188b2c0eb" + principalId = var.developer_group_principal_id + } + } +} +``` + +RBAC role IDs: +- Azure Kubernetes Service Cluster User Role: `4abbcc35-e782-43d8-92c5-2d3f1bd2253f` +- Azure Kubernetes Service RBAC Admin: `3498e952-d568-435e-9b2c-8d77e338d7f7` +- Azure Kubernetes Service RBAC Writer: `a7ffa36f-339b-4b5c-8bdf-e2c188b2c0eb` +- Azure Kubernetes Service RBAC Reader: `7f6c6a51-bcf8-42ba-9220-52d62157d06d` + +### Private Endpoint + +AKS uses **private cluster** mode rather than traditional private endpoints: + +```hcl +# For private cluster, add these properties to the managedClusters resource: +resource "azapi_resource" "this" { + # ... (same as basic, plus in body.properties:) + + body = { + properties = { + # ... other properties ... + apiServerAccessProfile = { + enablePrivateCluster = true + privateDNSZone = "system" # or custom zone resource ID + enablePrivateClusterPublicFQDN = false + } + } + } +} +``` + +Private DNS zone: `privatelink..azmk8s.io` + +**Note:** Private clusters require VPN, ExpressRoute, or a jump box to access the API server. Unless told otherwise, public API server access should be disabled per governance policy — use a Bastion host or VPN for access. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the AKS cluster') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('DNS prefix for the cluster') +param dnsPrefix string + +@description('Kubernetes version') +param kubernetesVersion string = '1.29' + +@description('Admin group object IDs for cluster admin access') +param adminGroupObjectIds array = [] + +@description('Tags to apply') +param tags object = {} + +resource aks 'Microsoft.ContainerService/managedClusters@2024-03-02-preview' = { + name: name + location: location + tags: tags + sku: { + name: 'Base' + tier: 'Free' + } + identity: { + type: 'SystemAssigned' + } + properties: { + kubernetesVersion: kubernetesVersion + dnsPrefix: dnsPrefix + agentPoolProfiles: [ + { + name: 'system' + count: 1 + vmSize: 'Standard_B2s' + osDiskSizeGB: 30 + mode: 'System' + osType: 'Linux' + } + ] + networkProfile: { + networkPlugin: 'azure' + networkPolicy: 'azure' + serviceCidr: '10.0.0.0/16' + dnsServiceIP: '10.0.0.10' + } + oidcIssuerProfile: { + enabled: true + } + securityProfile: { + workloadIdentity: { + enabled: true + } + } + aadProfile: { + managed: true + enableAzureRBAC: true + adminGroupObjectIDs: adminGroupObjectIds + } + } +} + +output id string = aks.id +output name string = aks.name +output fqdn string = aks.properties.fqdn +output kubeletIdentityObjectId string = aks.properties.identityProfile.kubeletidentity.objectId +``` + +### RBAC Assignment + +```bicep +@description('ACR resource ID for AcrPull') +param acrId string + +// AcrPull role for kubelet identity +var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d' + +resource acrPullAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(acrId, aks.properties.identityProfile.kubeletidentity.objectId, acrPullRoleId) + scope: resourceId('Microsoft.ContainerRegistry/registries', split(acrId, '/')[8]) + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId) + principalId: aks.properties.identityProfile.kubeletidentity.objectId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +AKS application code is standard Kubernetes -- Docker containers deployed via manifests, Helm charts, or Kustomize. + +### Kubernetes Deployment with Workload Identity + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp +spec: + replicas: 2 + selector: + matchLabels: + app: myapp + template: + metadata: + labels: + app: myapp + azure.workload.identity/use: "true" # Enable workload identity + spec: + serviceAccountName: myapp-sa # Linked to Azure managed identity + containers: + - name: myapp + image: myregistry.azurecr.io/myapp:latest + ports: + - containerPort: 8080 + env: + - name: AZURE_CLIENT_ID + value: "" # From federated credential + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 500m + memory: 256Mi +--- +apiVersion: v1 +kind: Service +metadata: + name: myapp +spec: + type: ClusterIP + selector: + app: myapp + ports: + - port: 80 + targetPort: 8080 +``` + +### Workload Identity Service Account + +```yaml +# service-account.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: myapp-sa + annotations: + azure.workload.identity/client-id: "" +``` + +### Federated Credential (Terraform) + +```hcl +resource "azapi_resource" "federated_credential" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2023-01-31" + name = "aks-${var.namespace}-${var.service_account_name}" + parent_id = var.managed_identity_id + + body = { + properties = { + audiences = ["api://AzureADTokenExchange"] + issuer = azapi_resource.this.output.properties.oidcIssuerProfile.issuerURL + subject = "system:serviceaccount:${var.namespace}:${var.service_account_name}" + } + } +} +``` + +### Application Code with DefaultAzureCredential + +```python +# Application code is the same as any Azure SDK code +# Workload identity provides the token automatically +from azure.identity import DefaultAzureCredential +from azure.storage.blob import BlobServiceClient + +credential = DefaultAzureCredential() # Picks up workload identity in AKS +client = BlobServiceClient(account_url="https://mystorageaccount.blob.core.windows.net", credential=credential) +``` + +## Common Pitfalls + +1. **System node pool VM size too small** -- `Standard_B2s` works for POC but system pods (CoreDNS, kube-proxy, etc.) need ~500Mi memory. Don't go below B2s. +2. **Forgetting AcrPull role on kubelet identity** -- Without this, pods fail to pull images with `ImagePullBackOff`. Must assign the role to `kubelet_identity`, not the cluster identity. +3. **Network plugin choice is permanent** -- Cannot change from `kubelet` to `azure` or vice versa after cluster creation. Azure CNI Overlay is the recommended default. +4. **Workload identity requires OIDC issuer** -- Must enable `oidc_issuer_enabled` on the cluster AND create a `FederatedIdentityCredential` linking the Kubernetes service account to the Azure managed identity. +5. **Private cluster API server access** -- With `private_cluster_enabled = true`, `kubectl` commands fail unless you're on the VNet (VPN, bastion, or runner VM). For POC, keep API server public. +6. **Node pool naming constraints** -- Pool names must be lowercase, max 12 characters for Linux, 6 for Windows. No hyphens or underscores. +7. **Kubernetes version upgrades** -- AKS enforces version currency. Clusters on N-2 versions are auto-upgraded. Plan upgrade cadence. +8. **Ingress controller not included** -- AKS doesn't install an ingress controller by default. Deploy NGINX Ingress Controller or use the managed `app-routing` add-on. + +## Production Backlog Items + +- [ ] Upgrade to Standard tier for SLA (99.95% with availability zones) +- [ ] Enable availability zones on node pools +- [ ] Configure cluster auto-scaler with appropriate min/max +- [ ] Enable private cluster mode for API server +- [ ] Deploy network policies for namespace isolation +- [ ] Install and configure ingress controller (NGINX or app-routing add-on) +- [ ] Set up monitoring with Container Insights and Prometheus +- [ ] Configure Azure Policy for Kubernetes (pod security standards) +- [ ] Implement GitOps with Flux or ArgoCD for declarative deployments +- [ ] Configure node pool auto-upgrade channel +- [ ] Add separate user node pool for workloads +- [ ] Enable Defender for Containers for runtime threat protection diff --git a/azext_prototype/knowledge/services/api-management.md b/azext_prototype/knowledge/services/api-management.md index b6e911a..77ac060 100644 --- a/azext_prototype/knowledge/services/api-management.md +++ b/azext_prototype/knowledge/services/api-management.md @@ -1,259 +1,324 @@ -# Azure API Management -> Managed API gateway for publishing, securing, transforming, and monitoring APIs at scale. - -## When to Use - -- **API gateway** -- centralized entry point for backend APIs with authentication, rate limiting, and caching -- **API versioning and lifecycle** -- manage multiple API versions, deprecation, and developer portal -- **Backend protection** -- shield backend services from direct internet exposure -- **API composition** -- aggregate multiple microservices behind a single facade -- **Cross-cutting concerns** -- apply policies (throttling, transformation, logging) without modifying backend code -- **Developer portal** -- self-service API documentation and subscription management - -Prefer API Management when you have multiple APIs or need centralized governance. For simple single-API scenarios, consider using Container Apps or App Service built-in routing instead. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | Consumption | No infrastructure cost when idle; pay per execution | -| SKU (alternative) | Developer | Full feature set for development/testing; single-instance, no SLA | -| Managed identity | System-assigned | For authenticating to backend APIs | -| Public network access | Enabled (POC) | Flag VNet integration as production backlog item | - -**CRITICAL:** Non-Consumption tier deployments take **30-45 minutes**. Plan for this in deployment timelines. The v2 SKUs (BasicV2, StandardV2) offer significantly faster deployment times (5-15 minutes). - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_api_management" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - publisher_name = var.publisher_name - publisher_email = var.publisher_email - sku_name = "Consumption_0" # Or "Developer_1" for full features - - identity { - type = "SystemAssigned" - } - - tags = var.tags -} - -# API definition -resource "azurerm_api_management_api" "example" { - name = "example-api" - resource_group_name = var.resource_group_name - api_management_name = azurerm_api_management.this.name - revision = "1" - display_name = "Example API" - path = "example" - protocols = ["https"] - service_url = var.backend_url # Backend API endpoint - - subscription_required = true -} - -# API operation -resource "azurerm_api_management_api_operation" "get_items" { - operation_id = "get-items" - api_name = azurerm_api_management_api.example.name - api_management_name = azurerm_api_management.this.name - resource_group_name = var.resource_group_name - display_name = "Get Items" - method = "GET" - url_template = "/items" - - response { - status_code = 200 - } -} -``` - -### RBAC Assignment - -```hcl -# API Management Service Contributor -- manage APIM instance -resource "azurerm_role_assignment" "apim_contributor" { - scope = azurerm_api_management.this.id - role_definition_name = "API Management Service Contributor" - principal_id = var.managed_identity_principal_id -} - -# Grant APIM's managed identity access to backend services -resource "azurerm_role_assignment" "apim_to_backend" { - scope = var.backend_resource_id - role_definition_name = var.backend_role_name # e.g., "Cognitive Services User" - principal_id = azurerm_api_management.this.identity[0].principal_id -} -``` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "apim" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_api_management.this.id - subresource_names = ["Gateway"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.azure-api.net` - -**Note:** Private endpoints are not supported on Consumption tier. Use Developer or higher for private endpoint support. - -### Backend Authentication Policy (Managed Identity) - -```hcl -resource "azurerm_api_management_api_policy" "managed_identity_auth" { - api_name = azurerm_api_management_api.example.name - api_management_name = azurerm_api_management.this.name - resource_group_name = var.resource_group_name - - xml_content = < - - - - - - - - - - - - - - -XML -} -``` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the API Management instance') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Publisher organization name') -param publisherName string - -@description('Publisher email address') -param publisherEmail string - -@description('Tags to apply') -param tags object = {} - -resource apim 'Microsoft.ApiManagement/service@2023-09-01-preview' = { - name: name - location: location - tags: tags - sku: { - name: 'Consumption' - capacity: 0 - } - identity: { - type: 'SystemAssigned' - } - properties: { - publisherName: publisherName - publisherEmail: publisherEmail - } -} - -output id string = apim.id -output name string = apim.name -output gatewayUrl string = apim.properties.gatewayUrl -output principalId string = apim.identity.principalId -``` - -### RBAC Assignment - -```bicep -@description('Backend resource ID for APIM to access') -param backendResourceId string - -@description('Role definition ID for backend access') -param backendRoleDefinitionId string - -resource backendRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(apim.id, backendResourceId, backendRoleDefinitionId) - scope: backendResourceId // Scope to the backend resource - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', backendRoleDefinitionId) - principalId: apim.identity.principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -No application code patterns for APIM itself -- it is an infrastructure/gateway service. Applications interact with APIM by calling the gateway URL instead of the backend URL directly. APIM policies handle authentication, transformation, and routing. - -### Calling APIs through APIM (Client Side) - -```python -# Python -- call API through APIM gateway -import requests - -apim_url = "https://myapim.azure-api.net/example/items" -headers = { - "Ocp-Apim-Subscription-Key": "", # For POC only -} -response = requests.get(apim_url, headers=headers) -``` - -For production, replace subscription keys with OAuth 2.0 / JWT validation policies. - -## Common Pitfalls - -1. **Long deployment times** -- Non-Consumption tier deployments take 30-45 minutes. The v2 SKUs (BasicV2, StandardV2) deploy in 5-15 minutes. Plan accordingly in automated pipelines. -2. **Consumption tier limitations** -- No VNet integration, no private endpoints, no developer portal customization, no built-in cache. Suitable for POC but not production workloads with those requirements. -3. **Backend authentication** -- Use `` policy to authenticate to backends. Never pass secrets through APIM policies. -4. **Subscription key exposure** -- Subscription keys (`Ocp-Apim-Subscription-Key`) are shared secrets. For production, implement OAuth 2.0 with `` policy instead. -5. **Policy XML errors** -- APIM policies use XML. Malformed XML silently breaks request processing. Always validate policy XML before deployment. -6. **CORS configuration** -- Forgetting CORS policies blocks browser-based API calls. Add `` policy in inbound for web frontends. -7. **Rate limiting scope** -- `` policy counts per subscription key by default. Use `` for per-IP or per-user throttling. - -## Production Backlog Items - -- [ ] Upgrade to Premium or StandardV2 tier for VNet integration and higher throughput -- [ ] Configure VNet integration (internal mode) to hide backend services from internet -- [ ] Set up custom domains with TLS certificates for the gateway and developer portal -- [ ] Implement caching policies to reduce backend load -- [ ] Configure rate limiting and quota policies per product/subscription -- [ ] Enable Application Insights integration for API analytics and diagnostics -- [ ] Implement OAuth 2.0 / JWT validation to replace subscription key authentication -- [ ] Configure named values with Key Vault references for policy secrets -- [ ] Set up CI/CD for API definitions using API Management DevOps Resource Kit -- [ ] Enable developer portal with customized branding and documentation +--- +service_namespace: Microsoft.ApiManagement/service +display_name: Azure API Management +--- + +# Azure API Management +> Managed API gateway for publishing, securing, transforming, and monitoring APIs at scale. + +## When to Use + +- **API gateway** -- centralized entry point for backend APIs with authentication, rate limiting, and caching +- **API versioning and lifecycle** -- manage multiple API versions, deprecation, and developer portal +- **Backend protection** -- shield backend services from direct internet exposure +- **API composition** -- aggregate multiple microservices behind a single facade +- **Cross-cutting concerns** -- apply policies (throttling, transformation, logging) without modifying backend code +- **Developer portal** -- self-service API documentation and subscription management + +Prefer API Management when you have multiple APIs or need centralized governance. For simple single-API scenarios, consider using Container Apps or App Service built-in routing instead. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Consumption | No infrastructure cost when idle; pay per execution | +| SKU (alternative) | Developer | Full feature set for development/testing; single-instance, no SLA | +| Managed identity | System-assigned | For authenticating to backend APIs | +| Public network access | Disabled (unless user overrides) | Flag VNet integration as production backlog item | + +**CRITICAL:** Non-Consumption tier deployments take **30-45 minutes**. Plan for this in deployment timelines. The v2 SKUs (BasicV2, StandardV2) offer significantly faster deployment times (5-15 minutes). + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.ApiManagement/service@2023-09-01-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Consumption" + capacity = 0 # Or "Developer" with capacity 1 for full features + } + properties = { + publisherName = var.publisher_name + publisherEmail = var.publisher_email + } + } + + tags = var.tags + + response_export_values = ["*"] +} + +# API definition +resource "azapi_resource" "example_api" { + type = "Microsoft.ApiManagement/service/apis@2023-09-01-preview" + name = "example-api" + parent_id = azapi_resource.this.id + + body = { + properties = { + displayName = "Example API" + path = "example" + protocols = ["https"] + serviceUrl = var.backend_url # Backend API endpoint + apiRevision = "1" + subscriptionRequired = true + } + } +} + +# API operation +resource "azapi_resource" "get_items" { + type = "Microsoft.ApiManagement/service/apis/operations@2023-09-01-preview" + name = "get-items" + parent_id = azapi_resource.example_api.id + + body = { + properties = { + displayName = "Get Items" + method = "GET" + urlTemplate = "/items" + responses = [ + { + statusCode = 200 + } + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# API Management Service Contributor -- manage APIM instance +resource "azapi_resource" "apim_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-apim-contributor") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/312a565d-c81f-4fd8-895a-4e21e48d571c" + principalId = var.managed_identity_principal_id + } + } +} + +# Grant APIM's managed identity access to backend services +resource "azapi_resource" "apim_to_backend" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.backend_resource_id}-apim-backend") + parent_id = var.backend_resource_id + + body = { + properties = { + roleDefinitionId = var.backend_role_definition_id # e.g., Cognitive Services User role ID + principalId = azapi_resource.this.output.identity.principalId + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "apim_pe" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.this.id + groupIds = ["Gateway"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "apim_pe_dns" { + count = var.enable_private_endpoint && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.apim_pe[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.azure-api.net` + +**Note:** Private endpoints are not supported on Consumption tier. Use Developer or higher for private endpoint support. + +### Backend Authentication Policy (Managed Identity) + +```hcl +resource "azapi_resource" "managed_identity_auth_policy" { + type = "Microsoft.ApiManagement/service/apis/policies@2023-09-01-preview" + name = "policy" + parent_id = azapi_resource.example_api.id + + body = { + properties = { + format = "xml" + value = < + + + + + + + + + + + + + + +XML + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the API Management instance') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Publisher organization name') +param publisherName string + +@description('Publisher email address') +param publisherEmail string + +@description('Tags to apply') +param tags object = {} + +resource apim 'Microsoft.ApiManagement/service@2023-09-01-preview' = { + name: name + location: location + tags: tags + sku: { + name: 'Consumption' + capacity: 0 + } + identity: { + type: 'SystemAssigned' + } + properties: { + publisherName: publisherName + publisherEmail: publisherEmail + } +} + +output id string = apim.id +output name string = apim.name +output gatewayUrl string = apim.properties.gatewayUrl +output principalId string = apim.identity.principalId +``` + +### RBAC Assignment + +```bicep +@description('Backend resource ID for APIM to access') +param backendResourceId string + +@description('Role definition ID for backend access') +param backendRoleDefinitionId string + +resource backendRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(apim.id, backendResourceId, backendRoleDefinitionId) + scope: backendResourceId // Scope to the backend resource + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', backendRoleDefinitionId) + principalId: apim.identity.principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +No application code patterns for APIM itself -- it is an infrastructure/gateway service. Applications interact with APIM by calling the gateway URL instead of the backend URL directly. APIM policies handle authentication, transformation, and routing. + +### Calling APIs through APIM (Client Side) + +```python +# Python -- call API through APIM gateway +import requests + +apim_url = "https://myapim.azure-api.net/example/items" +headers = { + "Ocp-Apim-Subscription-Key": "", # For POC only +} +response = requests.get(apim_url, headers=headers) +``` + +For production, replace subscription keys with OAuth 2.0 / JWT validation policies. + +## Common Pitfalls + +1. **Long deployment times** -- Non-Consumption tier deployments take 30-45 minutes. The v2 SKUs (BasicV2, StandardV2) deploy in 5-15 minutes. Plan accordingly in automated pipelines. +2. **Consumption tier limitations** -- No VNet integration, no private endpoints, no developer portal customization, no built-in cache. Suitable for POC but not production workloads with those requirements. +3. **Backend authentication** -- Use `` policy to authenticate to backends. Never pass secrets through APIM policies. +4. **Subscription key exposure** -- Subscription keys (`Ocp-Apim-Subscription-Key`) are shared secrets. For production, implement OAuth 2.0 with `` policy instead. +5. **Policy XML errors** -- APIM policies use XML. Malformed XML silently breaks request processing. Always validate policy XML before deployment. +6. **CORS configuration** -- Forgetting CORS policies blocks browser-based API calls. Add `` policy in inbound for web frontends. +7. **Rate limiting scope** -- `` policy counts per subscription key by default. Use `` for per-IP or per-user throttling. + +## Production Backlog Items + +- [ ] Upgrade to Premium or StandardV2 tier for VNet integration and higher throughput +- [ ] Configure VNet integration (internal mode) to hide backend services from internet +- [ ] Set up custom domains with TLS certificates for the gateway and developer portal +- [ ] Implement caching policies to reduce backend load +- [ ] Configure rate limiting and quota policies per product/subscription +- [ ] Enable Application Insights integration for API analytics and diagnostics +- [ ] Implement OAuth 2.0 / JWT validation to replace subscription key authentication +- [ ] Configure named values with Key Vault references for policy secrets +- [ ] Set up CI/CD for API definitions using API Management DevOps Resource Kit +- [ ] Enable developer portal with customized branding and documentation diff --git a/azext_prototype/knowledge/services/apim-api-operation.md b/azext_prototype/knowledge/services/apim-api-operation.md new file mode 100644 index 0000000..d71ac3c --- /dev/null +++ b/azext_prototype/knowledge/services/apim-api-operation.md @@ -0,0 +1,241 @@ +--- +service_namespace: Microsoft.ApiManagement/service/apis/operations +display_name: API Management API Operation +depends_on: + - Microsoft.ApiManagement/service/apis +--- + +# API Management API Operation + +> A single HTTP operation (GET, POST, PUT, DELETE, etc.) within an APIM API that maps a frontend URL pattern to a backend endpoint with optional policies. + +## When to Use +- Define individual endpoints within an API (e.g., GET /users, POST /orders) +- Apply operation-specific policies (caching on GET, validation on POST) +- Configure request/response schemas for developer portal documentation +- Map frontend URL templates to different backend paths +- Required for manually-defined APIs (auto-created when importing OpenAPI specs) + +## POC Defaults +- **Method**: GET, POST, PUT, DELETE as needed +- **URL template**: RESTful pattern (e.g., `/users/{id}`) +- **Response**: 200 OK with JSON content type + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "apim_operation_get" { + type = "Microsoft.ApiManagement/service/apis/operations@2024-05-01" + name = "get-items" + parent_id = azapi_resource.apim_api.id + + body = { + properties = { + displayName = "Get Items" + method = "GET" + urlTemplate = "/items" + description = "Retrieve all items" + responses = [ + { + statusCode = 200 + description = "Success" + representations = [ + { contentType = "application/json" } + ] + } + ] + } + } +} + +resource "azapi_resource" "apim_operation_get_by_id" { + type = "Microsoft.ApiManagement/service/apis/operations@2024-05-01" + name = "get-item-by-id" + parent_id = azapi_resource.apim_api.id + + body = { + properties = { + displayName = "Get Item by ID" + method = "GET" + urlTemplate = "/items/{id}" + description = "Retrieve a single item by ID" + templateParameters = [ + { + name = "id" + type = "string" + required = true + } + ] + responses = [ + { + statusCode = 200 + description = "Success" + representations = [ + { contentType = "application/json" } + ] + }, + { + statusCode = 404 + description = "Not found" + } + ] + } + } +} + +resource "azapi_resource" "apim_operation_post" { + type = "Microsoft.ApiManagement/service/apis/operations@2024-05-01" + name = "create-item" + parent_id = azapi_resource.apim_api.id + + body = { + properties = { + displayName = "Create Item" + method = "POST" + urlTemplate = "/items" + description = "Create a new item" + request = { + representations = [ + { contentType = "application/json" } + ] + } + responses = [ + { + statusCode = 201 + description = "Created" + representations = [ + { contentType = "application/json" } + ] + } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Operation management inherits from the APIM service and API RBAC. +# API Management Service Contributor role allows operation management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource getItems 'Microsoft.ApiManagement/service/apis/operations@2024-05-01' = { + parent: api + name: 'get-items' + properties: { + displayName: 'Get Items' + method: 'GET' + urlTemplate: '/items' + description: 'Retrieve all items' + responses: [ + { + statusCode: 200 + description: 'Success' + representations: [ + { contentType: 'application/json' } + ] + } + ] + } +} + +resource getItemById 'Microsoft.ApiManagement/service/apis/operations@2024-05-01' = { + parent: api + name: 'get-item-by-id' + properties: { + displayName: 'Get Item by ID' + method: 'GET' + urlTemplate: '/items/{id}' + templateParameters: [ + { + name: 'id' + type: 'string' + required: true + } + ] + responses: [ + { statusCode: 200, description: 'Success' } + { statusCode: 404, description: 'Not found' } + ] + } +} +``` + +## Application Code + +### Python +```python +# Operations are infrastructure — clients call the API through the APIM gateway. +# The operation defines the URL pattern; the backend handles the logic. +import requests + +apim_base = "https://.azure-api.net/" +headers = {"Ocp-Apim-Subscription-Key": subscription_key} + +# GET /items (matches get-items operation) +items = requests.get(f"{apim_base}/items", headers=headers).json() + +# GET /items/{id} (matches get-item-by-id operation) +item = requests.get(f"{apim_base}/items/123", headers=headers).json() + +# POST /items (matches create-item operation) +new_item = requests.post(f"{apim_base}/items", json={"name": "Widget"}, headers=headers).json() +``` + +### C# +```csharp +using System.Net.Http; +using System.Text.Json; + +var client = new HttpClient(); +client.BaseAddress = new Uri("https://.azure-api.net//"); +client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey); + +// GET /items +var items = await client.GetFromJsonAsync>("items"); + +// GET /items/{id} +var item = await client.GetFromJsonAsync("items/123"); + +// POST /items +var response = await client.PostAsJsonAsync("items", new { name = "Widget" }); +``` + +### Node.js +```typescript +const apimBase = "https://.azure-api.net/"; +const headers = { "Ocp-Apim-Subscription-Key": subscriptionKey }; + +// GET /items +const items = await fetch(`${apimBase}/items`, { headers }).then(r => r.json()); + +// GET /items/{id} +const item = await fetch(`${apimBase}/items/123`, { headers }).then(r => r.json()); + +// POST /items +const newItem = await fetch(`${apimBase}/items`, { + method: "POST", + headers: { ...headers, "Content-Type": "application/json" }, + body: JSON.stringify({ name: "Widget" }), +}).then(r => r.json()); +``` + +## Common Pitfalls +- **Operation name uniqueness**: The `name` (resource name) must be unique within the API. It's used as the operation ID — use kebab-case descriptive names. +- **URL template conflicts**: Two operations with the same method and overlapping URL templates (e.g., `GET /items/{id}` and `GET /items/{name}`) create ambiguity. Use distinct patterns. +- **OpenAPI import overwrites**: If you import an OpenAPI spec and also define operations manually, the import replaces all operations. Choose one approach. +- **Template parameter declaration**: Parameters in the URL template (e.g., `{id}`) must be declared in `templateParameters`. Missing declarations cause 404 responses. +- **Policy scoping**: Operation-level policies override API-level policies. Use `` in operation policies to inherit parent policies. +- **Method case sensitivity**: The `method` property must be uppercase (`GET`, `POST`, not `get`, `post`). + +## Production Backlog Items +- Operation-level caching policies for GET endpoints +- Request validation policies (JSON schema, required headers) +- Response transformation and masking for sensitive data +- Per-operation rate limiting and quota policies +- Mock responses for development and testing diff --git a/azext_prototype/knowledge/services/apim-api-policy.md b/azext_prototype/knowledge/services/apim-api-policy.md new file mode 100644 index 0000000..37b036f --- /dev/null +++ b/azext_prototype/knowledge/services/apim-api-policy.md @@ -0,0 +1,138 @@ +--- +service_namespace: Microsoft.ApiManagement/service/apis/policies +display_name: API Management API Policy +depends_on: + - Microsoft.ApiManagement/service/apis +--- + +# API Management API Policy + +> XML-based policy document applied at the API scope to control inbound, backend, outbound, and error handling behavior for all operations under an API. + +## When to Use +- Apply cross-cutting concerns (authentication, rate limiting, caching, CORS) to all operations in an API +- Transform request/response payloads (JSON-to-XML, header injection, URL rewrite) +- Authenticate to backend services using managed identity tokens +- Implement retry, circuit breaker, or fallback logic at the gateway level +- Enforce IP filtering or JWT validation before requests reach the backend + +Policies can be applied at global, product, API, or operation scope. API-scope policies override global/product-scope and are overridden by operation-scope policies. Use `` to inherit from parent scopes. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Policy format | XML (raw) | `format: "xml"` or `"xml-link"` for external URL | +| CORS | Allow all origins | Tighten for production | +| Backend auth | Managed identity | `` in inbound | +| Rate limiting | None for POC | Add per-subscription or per-IP for production | +| Caching | Disabled | Enable for read-heavy APIs | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "api_policy" { + type = "Microsoft.ApiManagement/service/apis/policies@2023-09-01-preview" + name = "policy" + parent_id = azapi_resource.api.id + + body = { + properties = { + format = "xml" + value = < + + + + + * + + + GET + POST + PUT + DELETE + + +
Content-Type
+
Authorization
+ + + + + + + + + + + + + + +XML + } + } +} +``` + +### RBAC Assignment + +```hcl +# Policy management inherits from the parent APIM service RBAC. +# API Management Service Contributor (312a565d-c81f-4fd8-895a-4e21e48d571c) covers policy management. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Backend app ID URI for managed identity authentication') +param backendAppIdUri string + +resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2023-09-01-preview' = { + parent: api + name: 'policy' + properties: { + format: 'xml' + value: '*GETPOST
Content-Type
Authorization
' + } +} +``` + +**Tip:** For readability, store policy XML in a separate file and use `loadTextContent('policy.xml')` in Bicep. + +## Application Code + +### Python +Infrastructure -- transparent to application code. Policies execute at the APIM gateway layer; backend applications are unaware of them. + +### C# +Infrastructure -- transparent to application code. Policies execute at the APIM gateway layer; backend applications are unaware of them. + +### Node.js +Infrastructure -- transparent to application code. Policies execute at the APIM gateway layer; backend applications are unaware of them. + +## Common Pitfalls + +1. **Malformed XML breaks the entire API** -- A single missing closing tag or invalid attribute silently breaks request processing. Always validate XML before deployment. +2. **Forgetting ``** -- Without `` in each section, parent-scope policies (global, product) are not inherited. This can disable logging, rate limiting, or other global policies. +3. **Policy name must be `"policy"`** -- The resource name for an API-level policy must always be `"policy"`. Using any other name results in a deployment error. +4. **Managed identity resource vs audience confusion** -- The `resource` attribute on `` is the backend App ID URI, not the APIM resource ID. +5. **CORS policy must come before authentication** -- If CORS preflight requests (OPTIONS) are blocked by authentication, browsers cannot reach the API at all. +6. **XML special characters** -- Values containing `<`, `>`, `&` must be XML-escaped or wrapped in CDATA sections. Terraform heredocs with embedded XML are prone to this. +7. **Policy size limit** -- Policies have a 256 KB size limit. Embedding large XSLT transforms or schemas can exceed this. + +## Production Backlog Items + +- [ ] Replace wildcard CORS origins with specific allowed domains +- [ ] Add `` or `` policies for abuse protection +- [ ] Implement `` policy with Azure AD token validation +- [ ] Add response caching with `` / `` for read-heavy endpoints +- [ ] Configure `` policy for resilient backend communication +- [ ] Add `` policies to strip internal headers from outbound responses +- [ ] Implement `` policy to restrict access by client IP range +- [ ] Move policy XML to source-controlled files and deploy via CI/CD pipeline diff --git a/azext_prototype/knowledge/services/apim-api.md b/azext_prototype/knowledge/services/apim-api.md new file mode 100644 index 0000000..731b034 --- /dev/null +++ b/azext_prototype/knowledge/services/apim-api.md @@ -0,0 +1,164 @@ +--- +service_namespace: Microsoft.ApiManagement/service/apis +display_name: API Management API +depends_on: + - Microsoft.ApiManagement/service +--- + +# API Management API + +> An API definition within an Azure API Management (APIM) instance that exposes backend services through a managed gateway with policies for authentication, rate limiting, transformation, and caching. + +## When to Use +- Expose backend APIs (Azure Functions, App Service, AKS) through a managed gateway +- Apply cross-cutting concerns (auth, rate limiting, CORS, caching) without changing backend code +- Provide a unified API surface for multiple backend services +- Generate developer portal documentation from OpenAPI specs +- Version and revision management for API lifecycle + +## POC Defaults +- **API type**: HTTP (REST) +- **Subscription required**: true (API key authentication) +- **Protocols**: HTTPS only +- **Path**: API-specific prefix (e.g., `/orders`, `/products`) +- **Backend URL**: The actual backend service URL + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "apim_api" { + type = "Microsoft.ApiManagement/service/apis@2024-05-01" + name = var.api_name + parent_id = azapi_resource.apim.id + + body = { + properties = { + displayName = var.display_name + path = var.api_path + protocols = ["https"] + subscriptionRequired = true + serviceUrl = var.backend_url + apiType = "http" + description = var.description + subscriptionKeyParameterNames = { + header = "Ocp-Apim-Subscription-Key" + query = "subscription-key" + } + } + } +} + +# Import from OpenAPI specification +resource "azapi_resource" "apim_api_openapi" { + type = "Microsoft.ApiManagement/service/apis@2024-05-01" + name = var.api_name + parent_id = azapi_resource.apim.id + + body = { + properties = { + displayName = var.display_name + path = var.api_path + protocols = ["https"] + format = "openapi+json" + value = file("${path.module}/openapi.json") + serviceUrl = var.backend_url + } + } +} +``` + +### RBAC Assignment +```hcl +# API Management Service Contributor role allows API management. +# For developer portal access, use API Management Developer Portal Content Editor. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param apiName string +param displayName string +param apiPath string +param backendUrl string + +resource api 'Microsoft.ApiManagement/service/apis@2024-05-01' = { + parent: apimService + name: apiName + properties: { + displayName: displayName + path: apiPath + protocols: ['https'] + subscriptionRequired: true + serviceUrl: backendUrl + apiType: 'http' + subscriptionKeyParameterNames: { + header: 'Ocp-Apim-Subscription-Key' + query: 'subscription-key' + } + } +} + +output apiId string = api.id +``` + +## Application Code + +### Python +```python +import requests + +# Calling an API through APIM gateway +apim_url = "https://.azure-api.net//endpoint" +headers = { + "Ocp-Apim-Subscription-Key": subscription_key, + "Content-Type": "application/json" +} + +response = requests.get(apim_url, headers=headers) +print(response.json()) +``` + +### C# +```csharp +using System.Net.Http; + +var client = new HttpClient(); +client.BaseAddress = new Uri("https://.azure-api.net//"); +client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey); + +var response = await client.GetAsync("endpoint"); +var content = await response.Content.ReadAsStringAsync(); +Console.WriteLine(content); +``` + +### Node.js +```typescript +const response = await fetch( + "https://.azure-api.net//endpoint", + { + headers: { + "Ocp-Apim-Subscription-Key": subscriptionKey, + "Content-Type": "application/json", + }, + } +); +const data = await response.json(); +console.log(data); +``` + +## Common Pitfalls +- **Path uniqueness**: Each API must have a unique `path` within the APIM instance. Duplicate paths cause deployment failures. +- **ServiceUrl trailing slash**: Be consistent with trailing slashes on `serviceUrl`. Mismatches can cause double slashes or missing path segments in backend requests. +- **Subscription key header**: The default header `Ocp-Apim-Subscription-Key` must be included in requests. Forgetting it returns 401 Unauthorized. +- **API import replaces operations**: Importing from OpenAPI replaces all existing operations. Incremental updates require careful version management. +- **Backend authentication**: APIM subscription keys authenticate the client to APIM, not to the backend. Configure backend policies (managed identity, certificates) separately. +- **APIM provisioning time**: The Consumption and Developer tiers deploy in minutes, but Premium tier can take 30-45 minutes. + +## Production Backlog Items +- OAuth 2.0 / OpenID Connect authentication policies +- Rate limiting and quota policies per subscription +- Request/response transformation policies +- API versioning strategy (URL path, header, or query string) +- Developer portal customization and API documentation diff --git a/azext_prototype/knowledge/services/app-insights.md b/azext_prototype/knowledge/services/app-insights.md index 02c1325..e993582 100644 --- a/azext_prototype/knowledge/services/app-insights.md +++ b/azext_prototype/knowledge/services/app-insights.md @@ -1,343 +1,365 @@ -# Application Insights -> Application performance monitoring (APM) service that provides deep observability into application behavior, including request tracing, dependency tracking, exception logging, and live metrics. - -## When to Use - -- Monitoring web application performance (request rates, response times, failure rates) -- Distributed tracing across microservices -- Exception and error tracking with stack traces -- Custom metrics and event tracking for business telemetry -- Dependency tracking (database calls, HTTP requests, external service calls) -- Availability monitoring with URL ping tests -- NOT suitable for: infrastructure-only monitoring without application code (use Azure Monitor metrics), log-only scenarios (use Log Analytics directly), or high-volume IoT telemetry (use IoT Hub + Time Series Insights) - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Type | Workspace-based | Classic (standalone) is deprecated | -| Log Analytics workspace | Required | Must reference an existing workspace | -| Application type | web | Default for most scenarios | -| Sampling | Default (adaptive) | Reduces volume automatically | -| Retention | Inherited from workspace | 30 days default | - -**CRITICAL**: Workspace-based Application Insights requires a `workspace_id` parameter pointing to an existing Log Analytics workspace. Always create the Log Analytics workspace first. - -**Connection string is NOT a secret**: The Application Insights connection string contains the instrumentation key and ingestion endpoint. It is safe to include in application configuration, environment variables, and source code. It does not grant access to read telemetry data. - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_application_insights" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - workspace_id = var.log_analytics_workspace_id # REQUIRED for workspace-based - application_type = "web" - - tags = var.tags -} -``` - -### With Connection String Output - -```hcl -output "id" { - description = "Application Insights resource ID" - value = azurerm_application_insights.this.id -} - -output "instrumentation_key" { - description = "Instrumentation key (not a secret)" - value = azurerm_application_insights.this.instrumentation_key -} - -output "connection_string" { - description = "Connection string for SDK configuration (not a secret)" - value = azurerm_application_insights.this.connection_string -} - -output "app_id" { - description = "Application Insights application ID (for API queries)" - value = azurerm_application_insights.this.app_id -} -``` - -### Injecting into App Service / Functions - -```hcl -# Pass connection string to App Service via app_settings -resource "azurerm_linux_web_app" "this" { - # ... other config ... - - app_settings = { - "APPLICATIONINSIGHTS_CONNECTION_STRING" = azurerm_application_insights.this.connection_string - "ApplicationInsightsAgent_EXTENSION_VERSION" = "~3" # Auto-instrumentation for .NET - } -} - -# Pass connection string to Function App via app_settings -resource "azurerm_linux_function_app" "this" { - # ... other config ... - - app_settings = { - "APPLICATIONINSIGHTS_CONNECTION_STRING" = azurerm_application_insights.this.connection_string - "APPINSIGHTS_INSTRUMENTATIONKEY" = azurerm_application_insights.this.instrumentation_key - } -} -``` - -### RBAC Assignment - -```hcl -# Grant read access to telemetry data -resource "azurerm_role_assignment" "reader" { - scope = azurerm_application_insights.this.id - role_definition_name = "Application Insights Component Reader" - principal_id = var.reader_principal_id -} - -# Grant contributor access for managing settings -resource "azurerm_role_assignment" "contributor" { - scope = azurerm_application_insights.this.id - role_definition_name = "Application Insights Component Contributor" - principal_id = var.admin_principal_id -} -``` - -### Private Endpoint - -```hcl -# Application Insights does NOT have its own private endpoint. -# Private access is achieved via Azure Monitor Private Link Scope (AMPLS), -# which is shared with Log Analytics. -# See log-analytics.md for the AMPLS pattern. -# For POC, public ingestion endpoints are acceptable. -``` - -## Bicep Patterns - -### Basic Resource - -```bicep -param name string -param location string -param logAnalyticsWorkspaceId string -param tags object = {} - -resource appInsights 'Microsoft.Insights/components@2020-02-02' = { - name: name - location: location - kind: 'web' - properties: { - Application_Type: 'web' - WorkspaceResourceId: logAnalyticsWorkspaceId - IngestionMode: 'LogAnalytics' - } - tags: tags -} - -output id string = appInsights.id -output connectionString string = appInsights.properties.ConnectionString -output instrumentationKey string = appInsights.properties.InstrumentationKey -``` - -### RBAC Assignment - -```bicep -param principalId string - -resource appInsights 'Microsoft.Insights/components@2020-02-02' existing = { - name: appInsightsName -} - -// Application Insights Component Reader -resource readerRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(appInsights.id, principalId, 'reader') - scope: appInsights - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'aa49f09b-42d2-4ee6-8548-4c9c6fd4acbb') - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python (OpenTelemetry -- recommended for new apps) - -```python -import os -from azure.monitor.opentelemetry import configure_azure_monitor - -# Configure once at application startup -configure_azure_monitor( - connection_string=os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"), -) - -# After configuration, use standard OpenTelemetry APIs -from opentelemetry import trace, metrics - -tracer = trace.get_tracer(__name__) -meter = metrics.get_meter(__name__) - -request_counter = meter.create_counter("app.requests", description="Total requests") - -def handle_request(): - with tracer.start_as_current_span("handle_request") as span: - span.set_attribute("custom.attribute", "value") - request_counter.add(1) - # ... application logic ... -``` - -### Python (opencensus -- legacy, for existing apps) - -```python -import os -from opencensus.ext.azure import metrics_exporter -from opencensus.ext.azure.trace_exporter import AzureExporter -from opencensus.trace.samplers import ProbabilitySampler -from opencensus.trace.tracer import Tracer - -connection_string = os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING") - -tracer = Tracer( - exporter=AzureExporter(connection_string=connection_string), - sampler=ProbabilitySampler(1.0), -) - -# For Flask -from opencensus.ext.flask.flask_middleware import FlaskMiddleware -FlaskMiddleware(app, exporter=AzureExporter(connection_string=connection_string)) -``` - -### C# (ASP.NET Core -- OpenTelemetry recommended) - -```csharp -using Azure.Monitor.OpenTelemetry.AspNetCore; - -var builder = WebApplication.CreateBuilder(args); - -// Option 1: OpenTelemetry (recommended for new apps) -builder.Services.AddOpenTelemetry().UseAzureMonitor(options => -{ - options.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]; -}); - -// Option 2: Classic Application Insights SDK -// builder.Services.AddApplicationInsightsTelemetry(options => -// { -// options.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]; -// }); - -var app = builder.Build(); -app.MapGet("/", () => "Hello World"); -app.Run(); -``` - -### C# (Custom Telemetry) - -```csharp -using Microsoft.ApplicationInsights; -using Microsoft.ApplicationInsights.DataContracts; - -public class MyService -{ - private readonly TelemetryClient _telemetry; - - public MyService(TelemetryClient telemetry) - { - _telemetry = telemetry; - } - - public void ProcessOrder(string orderId) - { - _telemetry.TrackEvent("OrderProcessed", new Dictionary - { - ["OrderId"] = orderId - }); - - _telemetry.GetMetric("OrdersProcessed").TrackValue(1); - } -} -``` - -### Node.js (OpenTelemetry -- recommended) - -```javascript -const { useAzureMonitor } = require("@azure/monitor-opentelemetry"); - -// Configure at application entry point (before other imports) -useAzureMonitor({ - azureMonitorExporterOptions: { - connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING, - }, -}); - -// After configuration, use standard OpenTelemetry APIs -const { trace, metrics } = require("@opentelemetry/api"); - -const tracer = trace.getTracer("my-app"); -const meter = metrics.getMeter("my-app"); -const requestCounter = meter.createCounter("app.requests"); - -function handleRequest(req, res) { - const span = tracer.startSpan("handleRequest"); - requestCounter.add(1); - // ... application logic ... - span.end(); -} -``` - -### Node.js (Classic SDK -- legacy) - -```javascript -const appInsights = require("applicationinsights"); - -appInsights - .setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING) - .setAutoCollectRequests(true) - .setAutoCollectPerformance(true) - .setAutoCollectExceptions(true) - .setAutoCollectDependencies(true) - .start(); - -const client = appInsights.defaultClient; - -// Custom events -client.trackEvent({ name: "OrderProcessed", properties: { orderId: "123" } }); - -// Custom metrics -client.trackMetric({ name: "OrderValue", value: 99.99 }); -``` - -## Common Pitfalls - -| Pitfall | Impact | Prevention | -|---------|--------|-----------| -| Creating standalone (classic) App Insights | Classic mode is deprecated; no workspace integration | Always set `workspace_id` (Terraform) or `WorkspaceResourceId` (Bicep) | -| Missing Log Analytics workspace dependency | Deployment fails | Create Log Analytics workspace first; reference its ID | -| Treating connection string as a secret | Unnecessary complexity in secret management | Connection string is NOT a secret -- safe in app settings and environment variables | -| Not configuring sampling | High telemetry volume and unexpected costs | Use adaptive sampling (default) or configure fixed-rate sampling | -| Confusing instrumentation key vs connection string | SDK misconfiguration | Use connection string (newer, includes endpoint); instrumentation key is legacy | -| Auto-instrumentation not enabled | Missing telemetry for .NET apps on App Service | Set `ApplicationInsightsAgent_EXTENSION_VERSION` to `~3` in app settings | -| Multiple App Insights instances for one app | Fragmented telemetry, broken distributed tracing | Use a single App Insights resource per application (microservice) | -| Not linking App Insights to the correct workspace | Logs go to wrong workspace | Verify `workspace_id` points to the shared workspace | - -## Production Backlog Items - -| Item | Priority | Description | -|------|----------|-------------| -| Sampling configuration | P3 | Tune sampling rates to balance cost and observability (fixed-rate or adaptive) | -| Custom metrics | P3 | Implement custom business metrics for dashboards and alerting | -| Availability tests | P3 | Configure URL ping tests or multi-step web tests for uptime monitoring | -| Smart detection alerts | P3 | Review and configure smart detection rules for anomaly alerting | -| Application Map review | P4 | Verify distributed tracing connections appear correctly in Application Map | -| Live Metrics authorization | P3 | Configure authenticated access for Live Metrics Stream | -| Azure Monitor Private Link Scope | P1 | Route telemetry ingestion through AMPLS for private network environments | -| Continuous export / data export | P4 | Configure diagnostic settings for long-term telemetry archival | -| Workbooks and dashboards | P3 | Create custom Azure Monitor Workbooks for operational visibility | -| Cost optimization | P3 | Review daily data volume and configure daily cap if needed | +--- +service_namespace: Microsoft.Insights/components +display_name: Application Insights +depends_on: + - Microsoft.OperationalInsights/workspaces +--- + +# Application Insights +> Application performance monitoring (APM) service that provides deep observability into application behavior, including request tracing, dependency tracking, exception logging, and live metrics. + +## When to Use + +- Monitoring web application performance (request rates, response times, failure rates) +- Distributed tracing across microservices +- Exception and error tracking with stack traces +- Custom metrics and event tracking for business telemetry +- Dependency tracking (database calls, HTTP requests, external service calls) +- Availability monitoring with URL ping tests +- NOT suitable for: infrastructure-only monitoring without application code (use Azure Monitor metrics), log-only scenarios (use Log Analytics directly), or high-volume IoT telemetry (use IoT Hub + Time Series Insights) + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Type | Workspace-based | Classic (standalone) is deprecated | +| Log Analytics workspace | Required | Must reference an existing workspace | +| Application type | web | Default for most scenarios | +| Sampling | Default (adaptive) | Reduces volume automatically | +| Retention | Inherited from workspace | 30 days default | + +**CRITICAL**: Workspace-based Application Insights requires a `workspace_id` parameter pointing to an existing Log Analytics workspace. Always create the Log Analytics workspace first. + +**Connection string is NOT a secret**: The Application Insights connection string contains the instrumentation key and ingestion endpoint. It is safe to include in application configuration, environment variables, and source code. It does not grant access to read telemetry data. + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "app_insights" { + type = "Microsoft.Insights/components@2020-02-02" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "web" + properties = { + Application_Type = "web" + WorkspaceResourceId = var.log_analytics_workspace_id # REQUIRED for workspace-based + IngestionMode = "LogAnalytics" + } + } + + tags = var.tags + + response_export_values = ["properties.ConnectionString", "properties.InstrumentationKey", "properties.AppId"] +} +``` + +### With Connection String Output + +```hcl +output "id" { + description = "Application Insights resource ID" + value = azapi_resource.app_insights.id +} + +output "instrumentation_key" { + description = "Instrumentation key (not a secret)" + value = azapi_resource.app_insights.output.properties.InstrumentationKey +} + +output "connection_string" { + description = "Connection string for SDK configuration (not a secret)" + value = azapi_resource.app_insights.output.properties.ConnectionString +} + +output "app_id" { + description = "Application Insights application ID (for API queries)" + value = azapi_resource.app_insights.output.properties.AppId +} +``` + +### Injecting into App Service / Functions + +```hcl +# Pass connection string to App Service via app_settings +# (include these in the siteConfig.appSettings array of the azapi_resource for Microsoft.Web/sites) +# +# { name = "APPLICATIONINSIGHTS_CONNECTION_STRING", value = azapi_resource.app_insights.output.properties.ConnectionString } +# { name = "ApplicationInsightsAgent_EXTENSION_VERSION", value = "~3" } # Auto-instrumentation for .NET +# +# For Function Apps, also include: +# { name = "APPINSIGHTS_INSTRUMENTATIONKEY", value = azapi_resource.app_insights.output.properties.InstrumentationKey } +``` + +### RBAC Assignment + +```hcl +# Grant read access to telemetry data +resource "azapi_resource" "reader_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.app_insights.id}${var.reader_principal_id}reader") + parent_id = azapi_resource.app_insights.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/aa49f09b-42d2-4ee6-8548-4c9c6fd4acbb" # Application Insights Component Reader + principalId = var.reader_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant contributor access for managing settings +resource "azapi_resource" "contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.app_insights.id}${var.admin_principal_id}contributor") + parent_id = azapi_resource.app_insights.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ae349356-3a1b-4a5e-921d-050484c6347e" # Application Insights Component Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +# Application Insights does NOT have its own private endpoint. +# Private access is achieved via Azure Monitor Private Link Scope (AMPLS), +# which is shared with Log Analytics. +# See log-analytics.md for the AMPLS pattern. +# Unless told otherwise, public access is disabled per governance policy — use AMPLS for private ingestion. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param logAnalyticsWorkspaceId string +param tags object = {} + +resource appInsights 'Microsoft.Insights/components@2020-02-02' = { + name: name + location: location + kind: 'web' + properties: { + Application_Type: 'web' + WorkspaceResourceId: logAnalyticsWorkspaceId + IngestionMode: 'LogAnalytics' + } + tags: tags +} + +output id string = appInsights.id +output connectionString string = appInsights.properties.ConnectionString +output instrumentationKey string = appInsights.properties.InstrumentationKey +``` + +### RBAC Assignment + +```bicep +param principalId string + +resource appInsights 'Microsoft.Insights/components@2020-02-02' existing = { + name: appInsightsName +} + +// Application Insights Component Reader +resource readerRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(appInsights.id, principalId, 'reader') + scope: appInsights + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'aa49f09b-42d2-4ee6-8548-4c9c6fd4acbb') + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python (OpenTelemetry -- recommended for new apps) + +```python +import os +from azure.monitor.opentelemetry import configure_azure_monitor + +# Configure once at application startup +configure_azure_monitor( + connection_string=os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING"), +) + +# After configuration, use standard OpenTelemetry APIs +from opentelemetry import trace, metrics + +tracer = trace.get_tracer(__name__) +meter = metrics.get_meter(__name__) + +request_counter = meter.create_counter("app.requests", description="Total requests") + +def handle_request(): + with tracer.start_as_current_span("handle_request") as span: + span.set_attribute("custom.attribute", "value") + request_counter.add(1) + # ... application logic ... +``` + +### Python (opencensus -- legacy, for existing apps) + +```python +import os +from opencensus.ext.azure import metrics_exporter +from opencensus.ext.azure.trace_exporter import AzureExporter +from opencensus.trace.samplers import ProbabilitySampler +from opencensus.trace.tracer import Tracer + +connection_string = os.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING") + +tracer = Tracer( + exporter=AzureExporter(connection_string=connection_string), + sampler=ProbabilitySampler(1.0), +) + +# For Flask +from opencensus.ext.flask.flask_middleware import FlaskMiddleware +FlaskMiddleware(app, exporter=AzureExporter(connection_string=connection_string)) +``` + +### C# (ASP.NET Core -- OpenTelemetry recommended) + +```csharp +using Azure.Monitor.OpenTelemetry.AspNetCore; + +var builder = WebApplication.CreateBuilder(args); + +// Option 1: OpenTelemetry (recommended for new apps) +builder.Services.AddOpenTelemetry().UseAzureMonitor(options => +{ + options.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]; +}); + +// Option 2: Classic Application Insights SDK +// builder.Services.AddApplicationInsightsTelemetry(options => +// { +// options.ConnectionString = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"]; +// }); + +var app = builder.Build(); +app.MapGet("/", () => "Hello World"); +app.Run(); +``` + +### C# (Custom Telemetry) + +```csharp +using Microsoft.ApplicationInsights; +using Microsoft.ApplicationInsights.DataContracts; + +public class MyService +{ + private readonly TelemetryClient _telemetry; + + public MyService(TelemetryClient telemetry) + { + _telemetry = telemetry; + } + + public void ProcessOrder(string orderId) + { + _telemetry.TrackEvent("OrderProcessed", new Dictionary + { + ["OrderId"] = orderId + }); + + _telemetry.GetMetric("OrdersProcessed").TrackValue(1); + } +} +``` + +### Node.js (OpenTelemetry -- recommended) + +```javascript +const { useAzureMonitor } = require("@azure/monitor-opentelemetry"); + +// Configure at application entry point (before other imports) +useAzureMonitor({ + azureMonitorExporterOptions: { + connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING, + }, +}); + +// After configuration, use standard OpenTelemetry APIs +const { trace, metrics } = require("@opentelemetry/api"); + +const tracer = trace.getTracer("my-app"); +const meter = metrics.getMeter("my-app"); +const requestCounter = meter.createCounter("app.requests"); + +function handleRequest(req, res) { + const span = tracer.startSpan("handleRequest"); + requestCounter.add(1); + // ... application logic ... + span.end(); +} +``` + +### Node.js (Classic SDK -- legacy) + +```javascript +const appInsights = require("applicationinsights"); + +appInsights + .setup(process.env.APPLICATIONINSIGHTS_CONNECTION_STRING) + .setAutoCollectRequests(true) + .setAutoCollectPerformance(true) + .setAutoCollectExceptions(true) + .setAutoCollectDependencies(true) + .start(); + +const client = appInsights.defaultClient; + +// Custom events +client.trackEvent({ name: "OrderProcessed", properties: { orderId: "123" } }); + +// Custom metrics +client.trackMetric({ name: "OrderValue", value: 99.99 }); +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Creating standalone (classic) App Insights | Classic mode is deprecated; no workspace integration | Always set `workspace_id` (Terraform) or `WorkspaceResourceId` (Bicep) | +| Missing Log Analytics workspace dependency | Deployment fails | Create Log Analytics workspace first; reference its ID | +| Treating connection string as a secret | Unnecessary complexity in secret management | Connection string is NOT a secret -- safe in app settings and environment variables | +| Not configuring sampling | High telemetry volume and unexpected costs | Use adaptive sampling (default) or configure fixed-rate sampling | +| Confusing instrumentation key vs connection string | SDK misconfiguration | Use connection string (newer, includes endpoint); instrumentation key is legacy | +| Auto-instrumentation not enabled | Missing telemetry for .NET apps on App Service | Set `ApplicationInsightsAgent_EXTENSION_VERSION` to `~3` in app settings | +| Multiple App Insights instances for one app | Fragmented telemetry, broken distributed tracing | Use a single App Insights resource per application (microservice) | +| Not linking App Insights to the correct workspace | Logs go to wrong workspace | Verify `workspace_id` points to the shared workspace | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Sampling configuration | P3 | Tune sampling rates to balance cost and observability (fixed-rate or adaptive) | +| Custom metrics | P3 | Implement custom business metrics for dashboards and alerting | +| Availability tests | P3 | Configure URL ping tests or multi-step web tests for uptime monitoring | +| Smart detection alerts | P3 | Review and configure smart detection rules for anomaly alerting | +| Application Map review | P4 | Verify distributed tracing connections appear correctly in Application Map | +| Live Metrics authorization | P3 | Configure authenticated access for Live Metrics Stream | +| Azure Monitor Private Link Scope | P1 | Route telemetry ingestion through AMPLS for private network environments | +| Continuous export / data export | P4 | Configure diagnostic settings for long-term telemetry archival | +| Workbooks and dashboards | P3 | Create custom Azure Monitor Workbooks for operational visibility | +| Cost optimization | P3 | Review daily data volume and configure daily cap if needed | diff --git a/azext_prototype/knowledge/services/app-service-plan.md b/azext_prototype/knowledge/services/app-service-plan.md new file mode 100644 index 0000000..3215a4c --- /dev/null +++ b/azext_prototype/knowledge/services/app-service-plan.md @@ -0,0 +1,102 @@ +--- +service_namespace: Microsoft.Web/serverfarms +display_name: App Service Plan +--- + +# App Service Plan + +> Defines the compute resources (SKU, OS, scaling) that host Azure App Service and Function App instances. + +## When to Use +- Required parent resource for all App Service web apps and Function Apps +- Defines the pricing tier, OS, and scaling configuration +- Multiple apps can share a single plan for cost efficiency + +## POC Defaults +- **OS**: Linux (preferred for Python/Node); Windows for .NET Framework +- **SKU**: B1 (Basic) for realistic POC; F1 (Free) for minimal testing +- **Always On**: Enabled on B1+ (not available on F1/Consumption) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "linux" + sku = { + name = "B1" + tier = "Basic" + } + properties = { + reserved = true # Required for Linux + } + } + + tags = var.tags +} +``` + +### Functions Consumption Plan +```hcl +resource "azapi_resource" "functions_plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "functionapp" + sku = { + name = "Y1" + tier = "Dynamic" + } + properties = { + reserved = true + } + } + + tags = var.tags +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param planName string +param location string = resourceGroup().location +param tags object = {} + +resource servicePlan 'Microsoft.Web/serverfarms@2023-12-01' = { + name: planName + location: location + kind: 'linux' + sku: { + name: 'B1' + tier: 'Basic' + } + properties: { + reserved: true + } + tags: tags +} + +output planId string = servicePlan.id +output planName string = servicePlan.name +``` + +## Common Pitfalls +- **`reserved = true` for Linux**: Linux plans MUST set `reserved = true` or the plan defaults to Windows. +- **Free tier limitations**: F1 (Free) does not support Always On, custom domains, or TLS certificates. +- **Shared plans**: Multiple apps on one plan share CPU/memory. High-traffic apps should have dedicated plans. + +## Production Backlog Items +- Premium V3 plan for production workloads with predictable performance +- Autoscale rules based on CPU, memory, or HTTP queue length +- Zone redundancy for high availability diff --git a/azext_prototype/knowledge/services/app-service.md b/azext_prototype/knowledge/services/app-service.md index 3bdcf3e..a52fa03 100644 --- a/azext_prototype/knowledge/services/app-service.md +++ b/azext_prototype/knowledge/services/app-service.md @@ -1,360 +1,442 @@ -# Azure App Service (Web Apps) -> Fully managed platform for building, deploying, and scaling web applications with built-in CI/CD, autoscaling, and high availability. - -## When to Use - -- Web applications (APIs, SPAs with server-side rendering, full-stack apps) -- RESTful APIs that don't need containerization -- Applications requiring deployment slots for blue/green deployments -- Workloads where the simplicity of PaaS is preferred over containers -- When the team is familiar with App Service and does not need container orchestration -- NOT suitable for: long-running background jobs (use Functions or Container Apps), event-driven microservices, or workloads requiring custom OS-level access - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| OS | Linux | Preferred for Python/Node; Windows for .NET Framework | -| SKU | B1 (Basic) | F1 (Free) acceptable for hello-world; B1 for realistic POC | -| Runtime | Python 3.12 / Node 20 LTS / .NET 8 | Match project requirements | -| Always On | Enabled (B1+) | Not available on F1 | -| HTTPS Only | true | Enforced by policy | -| Minimum TLS | 1.2 | Enforced by policy | -| Health check | /health | Configure in app settings | -| Managed identity | User-assigned | Attached to the web app | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_service_plan" "this" { - name = var.plan_name - location = var.location - resource_group_name = var.resource_group_name - os_type = "Linux" - sku_name = var.sku_name # "B1" for POC - - tags = var.tags -} - -resource "azurerm_linux_web_app" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - service_plan_id = azurerm_service_plan.this.id - https_only = true - - identity { - type = "UserAssigned" - identity_ids = [var.managed_identity_id] - } - - site_config { - always_on = true - minimum_tls_version = "1.2" - health_check_path = "/health" - - application_stack { - python_version = "3.12" # or node_version, dotnet_version - } - } - - app_settings = merge(var.app_settings, { - "AZURE_CLIENT_ID" = var.managed_identity_client_id - # Use Key Vault references for secrets: - # "SECRET_NAME" = "@Microsoft.KeyVault(SecretUri=https://kv-name.vault.azure.net/secrets/secret-name)" - }) - - tags = var.tags -} -``` - -### Windows Web App (for .NET Framework) - -```hcl -resource "azurerm_service_plan" "this" { - name = var.plan_name - location = var.location - resource_group_name = var.resource_group_name - os_type = "Windows" - sku_name = var.sku_name - - tags = var.tags -} - -resource "azurerm_windows_web_app" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - service_plan_id = azurerm_service_plan.this.id - https_only = true - - identity { - type = "UserAssigned" - identity_ids = [var.managed_identity_id] - } - - site_config { - always_on = true - minimum_tls_version = "1.2" - health_check_path = "/health" - - application_stack { - dotnet_version = "v8.0" - } - } - - app_settings = merge(var.app_settings, { - "AZURE_CLIENT_ID" = var.managed_identity_client_id - }) - - tags = var.tags -} -``` - -### RBAC Assignment - -```hcl -# App Service itself does not typically receive RBAC roles; -# instead, its managed identity is granted roles on OTHER resources. -# Example: grant the web app's identity access to Key Vault secrets -resource "azurerm_role_assignment" "keyvault_secrets" { - scope = var.key_vault_id - role_definition_name = "Key Vault Secrets User" - principal_id = var.managed_identity_principal_id -} - -# Example: grant the web app's identity access to Storage -resource "azurerm_role_assignment" "storage_blob" { - scope = var.storage_account_id - role_definition_name = "Storage Blob Data Contributor" - principal_id = var.managed_identity_principal_id -} -``` - -### Private Endpoint - -```hcl -# Private endpoint for INBOUND access to the web app (not commonly needed for POC) -resource "azurerm_private_endpoint" "this" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_linux_web_app.this.id - subresource_names = ["sites"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} - -# VNet integration for OUTBOUND traffic (connects to private endpoints of backend services) -resource "azurerm_app_service_virtual_network_swift_connection" "this" { - count = var.integration_subnet_id != null ? 1 : 0 - app_service_id = azurerm_linux_web_app.this.id - subnet_id = var.integration_subnet_id -} -``` - -## Bicep Patterns - -### Basic Resource - -```bicep -param name string -param location string -param planName string -param skuName string = 'B1' -param managedIdentityId string -param managedIdentityClientId string -param runtimeStack string = 'PYTHON|3.12' -param tags object = {} - -resource servicePlan 'Microsoft.Web/serverfarms@2023-12-01' = { - name: planName - location: location - kind: 'linux' - sku: { - name: skuName - } - properties: { - reserved: true // Required for Linux - } - tags: tags -} - -resource webApp 'Microsoft.Web/sites@2023-12-01' = { - name: name - location: location - kind: 'app,linux' - identity: { - type: 'UserAssigned' - userAssignedIdentities: { - '${managedIdentityId}': {} - } - } - properties: { - serverFarmId: servicePlan.id - httpsOnly: true - siteConfig: { - alwaysOn: true - minTlsVersion: '1.2' - healthCheckPath: '/health' - linuxFxVersion: runtimeStack - appSettings: [ - { - name: 'AZURE_CLIENT_ID' - value: managedIdentityClientId - } - ] - } - } - tags: tags -} - -output id string = webApp.id -output name string = webApp.name -output defaultHostName string = webApp.properties.defaultHostName -``` - -### RBAC Assignment - -```bicep -param principalId string -param keyVaultId string - -resource kvRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(keyVaultId, principalId, '4633458b-17de-408a-b874-0445c86b69e6') - scope: keyVault - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') // Key Vault Secrets User - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python (Flask) - -```python -import os -from flask import Flask, jsonify -from azure.identity import ManagedIdentityCredential, DefaultAzureCredential - -app = Flask(__name__) - -def get_credential(): - client_id = os.getenv("AZURE_CLIENT_ID") - if client_id: - return ManagedIdentityCredential(client_id=client_id) - return DefaultAzureCredential() - -@app.route("/health") -def health(): - return jsonify({"status": "healthy"}) - -@app.route("/") -def index(): - return jsonify({"message": "Hello from App Service"}) - -if __name__ == "__main__": - app.run(host="0.0.0.0", port=int(os.getenv("PORT", "8000"))) -``` - -### C# (ASP.NET Core) - -```csharp -using Azure.Identity; - -var builder = WebApplication.CreateBuilder(args); - -// Register Azure credential for DI -var clientId = builder.Configuration["AZURE_CLIENT_ID"]; -builder.Services.AddSingleton(sp => - string.IsNullOrEmpty(clientId) - ? new DefaultAzureCredential() - : new ManagedIdentityCredential(clientId)); - -builder.Services.AddHealthChecks(); - -var app = builder.Build(); - -app.MapHealthChecks("/health"); -app.MapGet("/", () => Results.Ok(new { message = "Hello from App Service" })); - -app.Run(); -``` - -### Node.js (Express) - -```javascript -const express = require("express"); -const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); - -const app = express(); -const port = process.env.PORT || 8080; - -function getCredential() { - const clientId = process.env.AZURE_CLIENT_ID; - return clientId - ? new ManagedIdentityCredential(clientId) - : new DefaultAzureCredential(); -} - -app.get("/health", (req, res) => { - res.json({ status: "healthy" }); -}); - -app.get("/", (req, res) => { - res.json({ message: "Hello from App Service" }); -}); - -app.listen(port, () => { - console.log(`Server running on port ${port}`); -}); -``` - -## Common Pitfalls - -| Pitfall | Impact | Prevention | -|---------|--------|-----------| -| Forgetting `always_on` on B1+ | App unloads after idle period, causing cold-start latency | Set `always_on = true` in site_config | -| Using connection strings instead of managed identity | Secrets leaked in config, rotation burden | Always use `AZURE_CLIENT_ID` + RBAC | -| Not setting `WEBSITES_PORT` for custom containers | App Service cannot route traffic to app | Set `WEBSITES_PORT` to the container's listening port | -| F1/D1 SKU limitations | No always-on, no VNet integration, no deployment slots, no custom domains with SSL | Use B1 minimum for realistic POC | -| Missing health check path | No automatic instance replacement on failure | Configure `health_check_path` in site_config | -| Hardcoding secrets in app_settings | Secrets visible in portal and ARM templates | Use Key Vault references: `@Microsoft.KeyVault(SecretUri=...)` | -| Not enabling HTTPS-only | HTTP traffic allowed | Set `https_only = true` | -| Wrong Linux runtime string | App fails to start | Verify runtime string matches: `PYTHON\|3.12`, `NODE\|20-lts`, `DOTNETCORE\|8.0` | - -## Production Backlog Items - -| Item | Priority | Description | -|------|----------|-------------| -| Deployment slots | P2 | Configure staging slot with swap-based deployments for zero-downtime releases | -| Auto-scaling | P2 | Configure auto-scale rules based on CPU, memory, or HTTP queue length | -| Custom domain with TLS | P3 | Bind custom domain and configure managed or imported TLS certificate | -| VNet integration | P1 | Enable VNet integration for outbound traffic to reach private endpoints | -| Private endpoint (inbound) | P1 | Add private endpoint for the web app if it should not be publicly accessible | -| Diagnostic logging | P3 | Enable App Service logs and route to Log Analytics workspace | -| Backup configuration | P2 | Configure automated backups (requires Standard tier or higher) | -| IP restrictions | P1 | Restrict inbound access to known IP ranges or Front Door/APIM only | -| Authentication (Easy Auth) | P3 | Enable built-in authentication for end-user identity if applicable | -| Application Performance Monitoring | P3 | Integrate App Insights with auto-instrumentation for deep diagnostics | +--- +service_namespace: Microsoft.Web/sites +display_name: Azure App Service +depends_on: + - Microsoft.Web/serverfarms +--- + +# Azure App Service (Web Apps) +> Fully managed platform for building, deploying, and scaling web applications with built-in CI/CD, autoscaling, and high availability. + +## When to Use + +- Web applications (APIs, SPAs with server-side rendering, full-stack apps) +- RESTful APIs that don't need containerization +- Applications requiring deployment slots for blue/green deployments +- Workloads where the simplicity of PaaS is preferred over containers +- When the team is familiar with App Service and does not need container orchestration +- NOT suitable for: long-running background jobs (use Functions or Container Apps), event-driven microservices, or workloads requiring custom OS-level access + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| OS | Linux | Preferred for Python/Node; Windows for .NET Framework | +| SKU | B1 (Basic) | F1 (Free) acceptable for hello-world; B1 for realistic POC | +| Runtime | Python 3.12 / Node 20 LTS / .NET 8 | Match project requirements | +| Always On | Enabled (B1+) | Not available on F1 | +| HTTPS Only | true | Enforced by policy | +| Minimum TLS | 1.2 | Enforced by policy | +| Health check | /health | Configure in app settings | +| Managed identity | User-assigned | Attached to the web app | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "linux" + sku = { + name = var.sku_name # "B1" for POC + } + properties = { + reserved = true # Required for Linux + } + } + + tags = var.tags +} + +resource "azapi_resource" "web_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + kind = "app,linux" + properties = { + serverFarmId = azapi_resource.plan.id + httpsOnly = true + siteConfig = { + alwaysOn = true + minTlsVersion = "1.2" + healthCheckPath = "/health" + linuxFxVersion = "PYTHON|3.12" # or NODE|20-lts, DOTNETCORE|8.0 + appSettings = [ + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + } + # Use Key Vault references for secrets: + # { name = "SECRET_NAME", value = "@Microsoft.KeyVault(SecretUri=https://kv-name.vault.azure.net/secrets/secret-name)" } + ] + } + } + } + + tags = var.tags + + response_export_values = ["properties.defaultHostName"] +} +``` + +### Windows Web App (for .NET Framework) + +```hcl +resource "azapi_resource" "plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "windows" + sku = { + name = var.sku_name + } + properties = { + reserved = false + } + } + + tags = var.tags +} + +resource "azapi_resource" "web_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + kind = "app" + properties = { + serverFarmId = azapi_resource.plan.id + httpsOnly = true + siteConfig = { + alwaysOn = true + minTlsVersion = "1.2" + healthCheckPath = "/health" + netFrameworkVersion = "v8.0" + appSettings = [ + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + } + ] + } + } + } + + tags = var.tags + + response_export_values = ["properties.defaultHostName"] +} +``` + +### RBAC Assignment + +```hcl +# App Service itself does not typically receive RBAC roles; +# instead, its managed identity is granted roles on OTHER resources. +# Example: grant the web app's identity access to Key Vault secrets +resource "azapi_resource" "keyvault_secrets_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.key_vault_id}${var.managed_identity_principal_id}keyvault-secrets-user") + parent_id = var.key_vault_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" # Key Vault Secrets User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Example: grant the web app's identity access to Storage +resource "azapi_resource" "storage_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}${var.managed_identity_principal_id}storage-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +# Unless told otherwise, private endpoint for INBOUND access is required per governance policy +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.web_app.id + groupIds = ["sites"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} + +# VNet integration for OUTBOUND traffic (connects to private endpoints of backend services) +resource "azapi_update_resource" "vnet_integration" { + count = var.integration_subnet_id != null ? 1 : 0 + type = "Microsoft.Web/sites@2023-12-01" + resource_id = azapi_resource.web_app.id + + body = { + properties = { + virtualNetworkSubnetId = var.integration_subnet_id + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param planName string +param skuName string = 'B1' +param managedIdentityId string +param managedIdentityClientId string +param runtimeStack string = 'PYTHON|3.12' +param tags object = {} + +resource servicePlan 'Microsoft.Web/serverfarms@2023-12-01' = { + name: planName + location: location + kind: 'linux' + sku: { + name: skuName + } + properties: { + reserved: true // Required for Linux + } + tags: tags +} + +resource webApp 'Microsoft.Web/sites@2023-12-01' = { + name: name + location: location + kind: 'app,linux' + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + properties: { + serverFarmId: servicePlan.id + httpsOnly: true + siteConfig: { + alwaysOn: true + minTlsVersion: '1.2' + healthCheckPath: '/health' + linuxFxVersion: runtimeStack + appSettings: [ + { + name: 'AZURE_CLIENT_ID' + value: managedIdentityClientId + } + ] + } + } + tags: tags +} + +output id string = webApp.id +output name string = webApp.name +output defaultHostName string = webApp.properties.defaultHostName +``` + +### RBAC Assignment + +```bicep +param principalId string +param keyVaultId string + +resource kvRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVaultId, principalId, '4633458b-17de-408a-b874-0445c86b69e6') + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') // Key Vault Secrets User + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python (Flask) + +```python +import os +from flask import Flask, jsonify +from azure.identity import ManagedIdentityCredential, DefaultAzureCredential + +app = Flask(__name__) + +def get_credential(): + client_id = os.getenv("AZURE_CLIENT_ID") + if client_id: + return ManagedIdentityCredential(client_id=client_id) + return DefaultAzureCredential() + +@app.route("/health") +def health(): + return jsonify({"status": "healthy"}) + +@app.route("/") +def index(): + return jsonify({"message": "Hello from App Service"}) + +if __name__ == "__main__": + app.run(host="0.0.0.0", port=int(os.getenv("PORT", "8000"))) +``` + +### C# (ASP.NET Core) + +```csharp +using Azure.Identity; + +var builder = WebApplication.CreateBuilder(args); + +// Register Azure credential for DI +var clientId = builder.Configuration["AZURE_CLIENT_ID"]; +builder.Services.AddSingleton(sp => + string.IsNullOrEmpty(clientId) + ? new DefaultAzureCredential() + : new ManagedIdentityCredential(clientId)); + +builder.Services.AddHealthChecks(); + +var app = builder.Build(); + +app.MapHealthChecks("/health"); +app.MapGet("/", () => Results.Ok(new { message = "Hello from App Service" })); + +app.Run(); +``` + +### Node.js (Express) + +```javascript +const express = require("express"); +const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); + +const app = express(); +const port = process.env.PORT || 8080; + +function getCredential() { + const clientId = process.env.AZURE_CLIENT_ID; + return clientId + ? new ManagedIdentityCredential(clientId) + : new DefaultAzureCredential(); +} + +app.get("/health", (req, res) => { + res.json({ status: "healthy" }); +}); + +app.get("/", (req, res) => { + res.json({ message: "Hello from App Service" }); +}); + +app.listen(port, () => { + console.log(`Server running on port ${port}`); +}); +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Forgetting `always_on` on B1+ | App unloads after idle period, causing cold-start latency | Set `always_on = true` in site_config | +| Using connection strings instead of managed identity | Secrets leaked in config, rotation burden | Always use `AZURE_CLIENT_ID` + RBAC | +| Not setting `WEBSITES_PORT` for custom containers | App Service cannot route traffic to app | Set `WEBSITES_PORT` to the container's listening port | +| F1/D1 SKU limitations | No always-on, no VNet integration, no deployment slots, no custom domains with SSL | Use B1 minimum for realistic POC | +| Missing health check path | No automatic instance replacement on failure | Configure `health_check_path` in site_config | +| Hardcoding secrets in app_settings | Secrets visible in portal and ARM templates | Use Key Vault references: `@Microsoft.KeyVault(SecretUri=...)` | +| Not enabling HTTPS-only | HTTP traffic allowed | Set `https_only = true` | +| Wrong Linux runtime string | App fails to start | Verify runtime string matches: `PYTHON\|3.12`, `NODE\|20-lts`, `DOTNETCORE\|8.0` | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Deployment slots | P2 | Configure staging slot with swap-based deployments for zero-downtime releases | +| Auto-scaling | P2 | Configure auto-scale rules based on CPU, memory, or HTTP queue length | +| Custom domain with TLS | P3 | Bind custom domain and configure managed or imported TLS certificate | +| VNet integration | P1 | Enable VNet integration for outbound traffic to reach private endpoints | +| Private endpoint (inbound) | P1 | Add private endpoint for the web app if it should not be publicly accessible | +| Diagnostic logging | P3 | Enable App Service logs and route to Log Analytics workspace | +| Backup configuration | P2 | Configure automated backups (requires Standard tier or higher) | +| IP restrictions | P1 | Restrict inbound access to known IP ranges or Front Door/APIM only | +| Authentication (Easy Auth) | P3 | Enable built-in authentication for end-user identity if applicable | +| Application Performance Monitoring | P3 | Integrate App Insights with auto-instrumentation for deep diagnostics | diff --git a/azext_prototype/knowledge/services/application-gateway.md b/azext_prototype/knowledge/services/application-gateway.md new file mode 100644 index 0000000..0a1cb53 --- /dev/null +++ b/azext_prototype/knowledge/services/application-gateway.md @@ -0,0 +1,518 @@ +--- +service_namespace: Microsoft.Network/applicationGateways +display_name: Azure Application Gateway +--- + +# Azure Application Gateway +> Regional Layer 7 load balancer with SSL termination, URL-based routing, cookie-based session affinity, and optional Web Application Firewall (WAF) for web traffic. + +## When to Use + +- **Single-region L7 load balancing** -- route HTTP/HTTPS traffic to backend pools within a VNet +- **URL-based routing** -- route `/api/*` to one backend pool and `/static/*` to another +- **SSL termination** -- offload TLS at the gateway to reduce compute burden on backends +- **WAF protection (v2)** -- OWASP 3.2 rule sets for inbound traffic protection within a region +- **WebSocket and HTTP/2** -- full support for real-time and modern protocols +- NOT suitable for: global traffic distribution (use Front Door), TCP/UDP load balancing (use Load Balancer), or non-HTTP protocols + +Choose Application Gateway over Front Door when all backends are in a single region and you need VNet-internal L7 routing. Choose Front Door for multi-region or CDN scenarios. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Tier | Standard_v2 | WAF_v2 for WAF; v1 is legacy | +| SKU capacity | 1 (manual) | Auto-scale 1-2 for POC | +| Subnet | Dedicated /24 | AppGW requires its own subnet, no other resources | +| Frontend IP | Public | Private frontend for internal-only apps | +| Backend protocol | HTTPS | End-to-end TLS recommended | +| Health probe | /health | Custom probe path on backends | +| HTTP to HTTPS redirect | Enabled | Redirect listener on port 80 | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "public_ip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" # Required for AppGW v2 + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "application_gateway" { + type = "Microsoft.Network/applicationGateways@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + name = "Standard_v2" # or "WAF_v2" + tier = "Standard_v2" + capacity = 1 + } + gatewayIPConfigurations = [ + { + name = "appgw-ip-config" + properties = { + subnet = { + id = var.appgw_subnet_id # Dedicated subnet for AppGW + } + } + } + ] + frontendIPConfigurations = [ + { + name = "appgw-frontend-ip" + properties = { + publicIPAddress = { + id = azapi_resource.public_ip.id + } + } + } + ] + frontendPorts = [ + { + name = "port-443" + properties = { + port = 443 + } + } + { + name = "port-80" + properties = { + port = 80 + } + } + ] + backendAddressPools = [ + { + name = "default-backend-pool" + properties = { + backendAddresses = [ + { + fqdn = var.backend_fqdn # e.g., "myapp.azurewebsites.net" + } + ] + } + } + ] + backendHttpSettingsCollection = [ + { + name = "default-http-settings" + properties = { + port = 443 + protocol = "Https" + cookieBasedAffinity = "Disabled" + requestTimeout = 30 + pickHostNameFromBackendAddress = true + probe = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/probes/health-probe" + } + } + } + ] + httpListeners = [ + { + name = "https-listener" + properties = { + frontendIPConfiguration = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/frontendIPConfigurations/appgw-frontend-ip" + } + frontendPort = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/frontendPorts/port-443" + } + protocol = "Https" + sslCertificate = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/sslCertificates/default-cert" + } + } + } + { + name = "http-listener" + properties = { + frontendIPConfiguration = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/frontendIPConfigurations/appgw-frontend-ip" + } + frontendPort = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/frontendPorts/port-80" + } + protocol = "Http" + } + } + ] + requestRoutingRules = [ + { + name = "https-rule" + properties = { + priority = 100 + ruleType = "Basic" + httpListener = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/httpListeners/https-listener" + } + backendAddressPool = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/backendAddressPools/default-backend-pool" + } + backendHttpSettings = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/backendHttpSettingsCollection/default-http-settings" + } + } + } + { + name = "http-redirect-rule" + properties = { + priority = 200 + ruleType = "Basic" + httpListener = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/httpListeners/http-listener" + } + redirectConfiguration = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/redirectConfigurations/http-to-https" + } + } + } + ] + redirectConfigurations = [ + { + name = "http-to-https" + properties = { + redirectType = "Permanent" + targetListener = { + id = "${var.resource_group_id}/providers/Microsoft.Network/applicationGateways/${var.name}/httpListeners/https-listener" + } + includePath = true + includeQueryString = true + } + } + ] + probes = [ + { + name = "health-probe" + properties = { + protocol = "Https" + path = "/health" + interval = 30 + timeout = 30 + unhealthyThreshold = 3 + pickHostNameFromBackendHttpSettings = true + } + } + ] + sslCertificates = [ + { + name = "default-cert" + properties = { + keyVaultSecretId = var.ssl_certificate_secret_id # Key Vault certificate URI + } + } + ] + } + } + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] # For Key Vault certificate access + } + + tags = var.tags + + response_export_values = ["properties.frontendIPConfigurations[0].properties.publicIPAddress.id"] +} +``` + +### RBAC Assignment + +```hcl +# Grant AppGW managed identity access to Key Vault certificates +resource "azapi_resource" "keyvault_secrets_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.key_vault_id}${var.managed_identity_principal_id}keyvault-secrets-user") + parent_id = var.key_vault_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" # Key Vault Secrets User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Application Gateway does not use private endpoints -- it **is** the entry point. For private/internal-only deployments, use a private frontend IP configuration: + +```hcl +# Replace the public frontend IP with a private one +resource "azapi_resource" "application_gateway_internal" { + # Same as above, but replace frontendIPConfigurations with: + # frontendIPConfigurations = [ + # { + # name = "appgw-frontend-ip" + # properties = { + # subnet = { + # id = var.appgw_subnet_id + # } + # privateIPAllocationMethod = "Static" + # privateIPAddress = "10.0.5.10" + # } + # } + # ] +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Application Gateway') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Subnet ID for Application Gateway (dedicated subnet)') +param subnetId string + +@description('Backend FQDN') +param backendFqdn string + +@description('Key Vault certificate secret ID') +param sslCertificateSecretId string + +@description('User-assigned managed identity ID for Key Vault access') +param managedIdentityId string + +@description('Tags to apply') +param tags object = {} + +resource publicIp 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource appGateway 'Microsoft.Network/applicationGateways@2024-01-01' = { + name: name + location: location + tags: tags + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + properties: { + sku: { + name: 'Standard_v2' + tier: 'Standard_v2' + capacity: 1 + } + gatewayIPConfigurations: [ + { + name: 'appgw-ip-config' + properties: { + subnet: { + id: subnetId + } + } + } + ] + frontendIPConfigurations: [ + { + name: 'appgw-frontend-ip' + properties: { + publicIPAddress: { + id: publicIp.id + } + } + } + ] + frontendPorts: [ + { + name: 'port-443' + properties: { + port: 443 + } + } + { + name: 'port-80' + properties: { + port: 80 + } + } + ] + backendAddressPools: [ + { + name: 'default-backend-pool' + properties: { + backendAddresses: [ + { + fqdn: backendFqdn + } + ] + } + } + ] + backendHttpSettingsCollection: [ + { + name: 'default-http-settings' + properties: { + port: 443 + protocol: 'Https' + cookieBasedAffinity: 'Disabled' + requestTimeout: 30 + pickHostNameFromBackendAddress: true + } + } + ] + httpListeners: [ + { + name: 'https-listener' + properties: { + frontendIPConfiguration: { + id: resourceId('Microsoft.Network/applicationGateways/frontendIPConfigurations', name, 'appgw-frontend-ip') + } + frontendPort: { + id: resourceId('Microsoft.Network/applicationGateways/frontendPorts', name, 'port-443') + } + protocol: 'Https' + sslCertificate: { + id: resourceId('Microsoft.Network/applicationGateways/sslCertificates', name, 'default-cert') + } + } + } + { + name: 'http-listener' + properties: { + frontendIPConfiguration: { + id: resourceId('Microsoft.Network/applicationGateways/frontendIPConfigurations', name, 'appgw-frontend-ip') + } + frontendPort: { + id: resourceId('Microsoft.Network/applicationGateways/frontendPorts', name, 'port-80') + } + protocol: 'Http' + } + } + ] + requestRoutingRules: [ + { + name: 'https-rule' + properties: { + priority: 100 + ruleType: 'Basic' + httpListener: { + id: resourceId('Microsoft.Network/applicationGateways/httpListeners', name, 'https-listener') + } + backendAddressPool: { + id: resourceId('Microsoft.Network/applicationGateways/backendAddressPools', name, 'default-backend-pool') + } + backendHttpSettings: { + id: resourceId('Microsoft.Network/applicationGateways/backendHttpSettingsCollection', name, 'default-http-settings') + } + } + } + { + name: 'http-redirect-rule' + properties: { + priority: 200 + ruleType: 'Basic' + httpListener: { + id: resourceId('Microsoft.Network/applicationGateways/httpListeners', name, 'http-listener') + } + redirectConfiguration: { + id: resourceId('Microsoft.Network/applicationGateways/redirectConfigurations', name, 'http-to-https') + } + } + } + ] + redirectConfigurations: [ + { + name: 'http-to-https' + properties: { + redirectType: 'Permanent' + targetListener: { + id: resourceId('Microsoft.Network/applicationGateways/httpListeners', name, 'https-listener') + } + includePath: true + includeQueryString: true + } + } + ] + probes: [ + { + name: 'health-probe' + properties: { + protocol: 'Https' + path: '/health' + interval: 30 + timeout: 30 + unhealthyThreshold: 3 + pickHostNameFromBackendHttpSettings: true + } + } + ] + sslCertificates: [ + { + name: 'default-cert' + properties: { + keyVaultSecretId: sslCertificateSecretId + } + } + ] + } +} + +output id string = appGateway.id +output publicIpAddress string = publicIp.properties.ipAddress +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Not using a dedicated subnet | Deployment fails; AppGW requires exclusive subnet | Create a `/24` subnet with no other resources or delegations | +| Using Standard (v1) SKU | Missing auto-scale, zone redundancy, Key Vault integration | Always use `Standard_v2` or `WAF_v2` | +| Forgetting health probe customization | Default probe uses `/` which may return 404 on backends | Set probe path to `/health` and configure backend app accordingly | +| Self-referencing resource IDs | Complex nested ID references are error-prone | Use `resourceId()` in Bicep or construct IDs carefully in Terraform | +| SSL certificate Key Vault access | AppGW cannot fetch cert; deployment fails with 403 | Grant managed identity Key Vault Secrets User role | +| Not enabling HTTP-to-HTTPS redirect | Insecure HTTP traffic reaches backends | Add redirect configuration from port 80 listener to port 443 | +| Backend health showing unhealthy | Probe fails because backend rejects AppGW hostname | Set `pickHostNameFromBackendAddress = true` in probe and HTTP settings | +| Subnet too small | Cannot scale out AppGW instances | Use at least `/26` (59 usable IPs); `/24` recommended | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| WAF_v2 upgrade | P1 | Switch to WAF_v2 SKU and enable OWASP 3.2 managed rule sets | +| Auto-scaling | P2 | Configure auto-scale with min/max instance count instead of fixed capacity | +| Zone redundancy | P1 | Deploy across availability zones for 99.95% SLA | +| Custom domain + TLS | P2 | Bind custom domain and automate certificate rotation via Key Vault | +| Diagnostic logging | P2 | Enable access logs, firewall logs, and metrics to Log Analytics | +| URL-based routing | P3 | Separate API and static content to different backend pools | +| Connection draining | P2 | Enable connection draining for graceful backend removal during updates | +| Rewrite rules | P3 | Configure header rewrites for security headers (HSTS, CSP, etc.) | +| Private frontend | P2 | Add private frontend IP for internal-only traffic if needed | +| Backend authentication | P3 | Configure end-to-end TLS with trusted root certificates | diff --git a/azext_prototype/knowledge/services/automation-job-schedule.md b/azext_prototype/knowledge/services/automation-job-schedule.md new file mode 100644 index 0000000..edc2531 --- /dev/null +++ b/azext_prototype/knowledge/services/automation-job-schedule.md @@ -0,0 +1,151 @@ +--- +service_namespace: Microsoft.Automation/automationAccounts/jobSchedules +display_name: Automation Job Schedule +depends_on: + - Microsoft.Automation/automationAccounts + - Microsoft.Automation/automationAccounts/runbooks + - Microsoft.Automation/automationAccounts/schedules +--- + +# Automation Job Schedule + +> Links an Automation runbook to a schedule, causing the runbook to execute automatically at the times defined by the schedule. + +## When to Use +- Connect a schedule to a runbook for automated execution +- Pass parameters to a runbook on a scheduled basis +- Run the same runbook on different schedules with different parameters +- Every scheduled runbook execution requires this linking resource + +## POC Defaults +- **Name**: Auto-generated GUID (required by the API) +- **Parameters**: Empty or task-specific +- **Run on**: Azure sandbox (not Hybrid Worker) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "job_schedule" { + type = "Microsoft.Automation/automationAccounts/jobSchedules@2023-11-01" + name = var.job_schedule_guid + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + runbook = { + name = azapi_resource.runbook.name + } + schedule = { + name = azapi_resource.schedule.name + } + parameters = { + resourceGroupName = var.target_resource_group + action = "stop" + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Job schedule management inherits from the Automation Account RBAC. +# Automation Contributor role allows full job schedule management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param jobScheduleGuid string = newGuid() + +resource jobSchedule 'Microsoft.Automation/automationAccounts/jobSchedules@2023-11-01' = { + parent: automationAccount + name: jobScheduleGuid + properties: { + runbook: { + name: runbook.name + } + schedule: { + name: schedule.name + } + parameters: { + resourceGroupName: targetResourceGroup + action: 'stop' + } + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.automation import AutomationClient +import uuid + +credential = DefaultAzureCredential() +client = AutomationClient(credential, subscription_id) + +job_schedule = client.job_schedule.create( + resource_group_name=rg_name, + automation_account_name=account_name, + job_schedule_id=str(uuid.uuid4()), + parameters={ + "properties": { + "runbook": {"name": runbook_name}, + "schedule": {"name": schedule_name}, + "parameters": {"param1": "value1"} + } + } +) +print(f"Linked runbook '{runbook_name}' to schedule '{schedule_name}'") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.Automation; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var account = client.GetAutomationAccountResource( + AutomationAccountResource.CreateResourceIdentifier(subscriptionId, rgName, accountName)); + +// Job schedule linking via REST or SDK +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { AutomationClient } from "@azure/arm-automation"; +import { v4 as uuidv4 } from "uuid"; + +const credential = new DefaultAzureCredential(); +const client = new AutomationClient(credential, subscriptionId); + +await client.jobSchedule.create(rgName, accountName, uuidv4(), { + properties: { + runbook: { name: runbookName }, + schedule: { name: scheduleName }, + parameters: { param1: "value1" }, + }, +}); +``` + +## Common Pitfalls +- **Name must be a GUID**: The job schedule resource name must be a valid GUID, not a human-readable name. Using a non-GUID name causes a 400 error. +- **One runbook per schedule link**: A job schedule links exactly one runbook to one schedule. To run multiple runbooks on the same schedule, create multiple job schedules. +- **Parameters are strings**: All parameter values are passed as strings, even if the runbook parameter type is int or bool. The runbook must handle type conversion. +- **Deletion before recreation**: You cannot update a job schedule — you must delete and recreate it. This is important for Terraform's lifecycle management. +- **Runbook must be published**: The runbook must be in the Published state before it can be linked to a schedule. Draft runbooks cannot be scheduled. + +## Production Backlog Items +- Parameterized scheduling for different environments (dev, staging, prod) +- Hybrid Worker targeting for on-premises or network-restricted tasks +- Job schedule auditing and drift detection +- Alerting on job schedule failures or missed runs diff --git a/azext_prototype/knowledge/services/automation-runbook.md b/azext_prototype/knowledge/services/automation-runbook.md new file mode 100644 index 0000000..33923ec --- /dev/null +++ b/azext_prototype/knowledge/services/automation-runbook.md @@ -0,0 +1,165 @@ +--- +service_namespace: Microsoft.Automation/automationAccounts/runbooks +display_name: Automation Runbook +depends_on: + - Microsoft.Automation/automationAccounts +--- + +# Automation Runbook + +> A script (PowerShell, Python, or graphical) hosted in an Azure Automation Account that can be executed on-demand, on a schedule, or triggered by webhooks/alerts. + +## When to Use +- Automate operational tasks (start/stop VMs, rotate secrets, clean up resources) +- Remediation actions triggered by Azure Monitor alerts +- Scheduled maintenance scripts (database cleanup, log rotation) +- Cross-resource orchestration that doesn't need real-time execution +- NOT suitable for: sub-second event processing (use Functions), CI/CD (use GitHub Actions/ADO) + +## POC Defaults +- **Runbook type**: PowerShell72 (PowerShell 7.2 runtime) +- **State**: Published (New → Published on first publish) +- **Log verbose**: false +- **Log progress**: false + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "runbook" { + type = "Microsoft.Automation/automationAccounts/runbooks@2023-11-01" + name = var.runbook_name + parent_id = azapi_resource.automation_account.id + location = var.location + + body = { + properties = { + runbookType = "PowerShell72" + logVerbose = false + logProgress = false + description = var.description + draft = {} + publishContentLink = { + uri = var.script_uri + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Automation Operator role allows starting runbooks without editing them. +# Automation Contributor role allows full runbook management. +resource "azapi_resource" "runbook_operator" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.role_assignment_name + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/d3881f73-407a-4167-8283-e981cbba0404" + principalId = var.operator_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param runbookName string +param location string +param scriptUri string + +resource runbook 'Microsoft.Automation/automationAccounts/runbooks@2023-11-01' = { + parent: automationAccount + name: runbookName + location: location + properties: { + runbookType: 'PowerShell72' + logVerbose: false + logProgress: false + description: 'Automated operational task' + publishContentLink: { + uri: scriptUri + } + } +} + +output runbookName string = runbook.name +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.automation import AutomationClient + +credential = DefaultAzureCredential() +client = AutomationClient(credential, subscription_id) + +# Start a runbook job +job = client.job.create( + resource_group_name=rg_name, + automation_account_name=account_name, + job_name=str(uuid.uuid4()), + parameters={ + "properties": { + "runbook": {"name": runbook_name}, + "parameters": {"param1": "value1"} + } + } +) +print(f"Job status: {job.status}") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.Automation; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var automationAccount = client.GetAutomationAccountResource( + AutomationAccountResource.CreateResourceIdentifier(subscriptionId, rgName, accountName)); + +var runbook = await automationAccount.GetAutomationRunbookAsync(runbookName); +// Trigger via REST or use the Job resource +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { AutomationClient } from "@azure/arm-automation"; + +const credential = new DefaultAzureCredential(); +const client = new AutomationClient(credential, subscriptionId); + +const job = await client.job.create(rgName, accountName, jobName, { + properties: { + runbook: { name: runbookName }, + parameters: { param1: "value1" }, + }, +}); +console.log(`Job status: ${job.status}`); +``` + +## Common Pitfalls +- **Published vs Draft**: Runbooks start in Draft state. They must be published before they can be executed. The `publishContentLink` approach publishes automatically. +- **Script URI accessibility**: The `publishContentLink.uri` must be publicly accessible or use a SAS token. Private blob storage URIs without SAS fail silently. +- **Module dependencies**: PowerShell runbooks that import modules (Az.Accounts, etc.) require those modules to be installed in the Automation Account first. +- **Location must match**: The runbook location must match the parent Automation Account location. +- **Execution limits**: Runbook jobs have a 3-hour fair-share limit on cloud sandboxes. Use Hybrid Runbook Workers for long-running tasks. + +## Production Backlog Items +- Source control integration for runbook versioning +- Hybrid Runbook Worker for on-premises or long-running tasks +- Webhook triggers for event-driven runbook execution +- Error handling and retry logic within runbook scripts +- Monitoring and alerting on runbook job failures diff --git a/azext_prototype/knowledge/services/automation-schedule.md b/azext_prototype/knowledge/services/automation-schedule.md new file mode 100644 index 0000000..eb03fed --- /dev/null +++ b/azext_prototype/knowledge/services/automation-schedule.md @@ -0,0 +1,150 @@ +--- +service_namespace: Microsoft.Automation/automationAccounts/schedules +display_name: Automation Schedule +depends_on: + - Microsoft.Automation/automationAccounts +--- + +# Automation Schedule + +> A time-based trigger definition for Azure Automation that specifies when and how often runbooks should execute. + +## When to Use +- Run operational tasks on a recurring basis (daily cleanup, weekly reports) +- Schedule maintenance windows (start/stop VMs on business hours) +- One-time future execution of a runbook +- Combine with job schedules to link schedules to specific runbooks + +## POC Defaults +- **Frequency**: Day (daily execution) +- **Interval**: 1 (every day) +- **Time zone**: UTC +- **Start time**: Next day at 02:00 UTC (avoids immediate execution) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "schedule" { + type = "Microsoft.Automation/automationAccounts/schedules@2023-11-01" + name = var.schedule_name + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + description = var.description + startTime = var.start_time + frequency = "Day" + interval = 1 + timeZone = "UTC" + expiryTime = "9999-12-31T23:59:59+00:00" + advancedSchedule = {} + } + } +} +``` + +### RBAC Assignment +```hcl +# Schedule management inherits from the Automation Account RBAC. +# Automation Contributor role allows full schedule management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param scheduleName string +param startTime string + +resource schedule 'Microsoft.Automation/automationAccounts/schedules@2023-11-01' = { + parent: automationAccount + name: scheduleName + properties: { + description: 'Daily operational task schedule' + startTime: startTime + frequency: 'Day' + interval: 1 + timeZone: 'UTC' + expiryTime: '9999-12-31T23:59:59+00:00' + } +} + +output scheduleName string = schedule.name +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.automation import AutomationClient + +credential = DefaultAzureCredential() +client = AutomationClient(credential, subscription_id) + +schedule = client.schedule.create_or_update( + resource_group_name=rg_name, + automation_account_name=account_name, + schedule_name="daily-cleanup", + parameters={ + "properties": { + "startTime": "2025-01-01T02:00:00+00:00", + "frequency": "Day", + "interval": 1, + "timeZone": "UTC" + } + } +) +print(f"Schedule: {schedule.name}, Next run: {schedule.next_run}") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.Automation; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var account = client.GetAutomationAccountResource( + AutomationAccountResource.CreateResourceIdentifier(subscriptionId, rgName, accountName)); +var schedules = account.GetAutomationSchedules(); + +await schedules.CreateOrUpdateAsync(Azure.WaitUntil.Completed, "daily-cleanup", + new AutomationScheduleCreateOrUpdateContent("daily-cleanup", + DateTimeOffset.UtcNow.AddDays(1), AutomationScheduleFrequency.Day) { Interval = 1 }); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { AutomationClient } from "@azure/arm-automation"; + +const credential = new DefaultAzureCredential(); +const client = new AutomationClient(credential, subscriptionId); + +const schedule = await client.schedule.createOrUpdate(rgName, accountName, "daily-cleanup", { + properties: { + startTime: new Date(Date.now() + 86400000).toISOString(), + frequency: "Day", + interval: 1, + timeZone: "UTC", + }, +}); +console.log(`Schedule: ${schedule.name}, Next run: ${schedule.nextRun}`); +``` + +## Common Pitfalls +- **Start time must be in the future**: The API rejects schedules with a start time in the past. Always compute a future timestamp. +- **Schedule alone doesn't run anything**: A schedule must be linked to a runbook via a job schedule resource to actually trigger execution. +- **Time zone strings**: Use Windows time zone IDs (e.g., `Eastern Standard Time`), not IANA (e.g., `America/New_York`). UTC is the safest default. +- **Expired schedules cannot be reactivated**: Once a schedule passes its `expiryTime`, it must be recreated. Use a far-future expiry for indefinite schedules. +- **One-time vs recurring**: Set `frequency` to `OneTime` for single execution. There's no way to convert a one-time schedule to recurring. + +## Production Backlog Items +- Advanced schedule patterns (monthly on specific days, weekly on weekdays) +- Schedule monitoring and alerting for missed runs +- Schedule disable/enable automation for maintenance windows +- Time zone alignment with business operating hours diff --git a/azext_prototype/knowledge/services/automation.md b/azext_prototype/knowledge/services/automation.md new file mode 100644 index 0000000..cc68258 --- /dev/null +++ b/azext_prototype/knowledge/services/automation.md @@ -0,0 +1,268 @@ +--- +service_namespace: Microsoft.Automation/automationAccounts +display_name: Azure Automation +--- + +# Azure Automation +> Cloud-based automation service for process automation, configuration management, and update management using PowerShell and Python runbooks. + +## When to Use + +- Scheduled operational tasks (start/stop VMs, rotate keys, clean up resources) +- Configuration management with Azure Automation State Configuration (DSC) +- Runbook-based remediation triggered by Azure Monitor alerts +- Update management for OS patching across VMs +- Hybrid worker scenarios bridging on-premises and cloud automation +- NOT suitable for: event-driven real-time processing (use Azure Functions), CI/CD pipelines (use Azure DevOps/GitHub Actions), or complex workflow orchestration (use Logic Apps) + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | Free tier allows 500 minutes/month of job runtime | +| Identity | System-assigned managed identity | For accessing Azure resources from runbooks | +| Public network access | Enabled | Disable for production with private endpoints | +| Runbook type | PowerShell 7.2 | Python 3.8 also supported | +| Encryption | Platform-managed keys | CMK available for production | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "automation_account" { + type = "Microsoft.Automation/automationAccounts@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + sku = { + name = "Basic" + } + publicNetworkAccess = true # Set false for production + disableLocalAuth = false # Set true for production (Entra-only auth) + encryption = { + keySource = "Microsoft.Automation" + } + } + } + + tags = var.tags +} +``` + +### With Runbook + +```hcl +resource "azapi_resource" "runbook" { + type = "Microsoft.Automation/automationAccounts/runbooks@2023-11-01" + name = var.runbook_name + location = var.location + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + runbookType = "PowerShell72" + logProgress = true + logVerbose = false + description = var.runbook_description + publishContentLink = { + uri = var.runbook_script_uri # URI to the .ps1 script + } + } + } + + tags = var.tags +} +``` + +### With Schedule + +```hcl +resource "azapi_resource" "schedule" { + type = "Microsoft.Automation/automationAccounts/schedules@2023-11-01" + name = var.schedule_name + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + frequency = "Day" + interval = 1 + startTime = var.start_time # ISO 8601 format + timeZone = "UTC" + description = "Daily scheduled task" + } + } +} + +resource "azapi_resource" "job_schedule" { + type = "Microsoft.Automation/automationAccounts/jobSchedules@2023-11-01" + name = var.job_schedule_guid # Must be a GUID + parent_id = azapi_resource.automation_account.id + + body = { + properties = { + runbook = { + name = azapi_resource.runbook.name + } + schedule = { + name = azapi_resource.schedule.name + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# Grant the automation account's managed identity Contributor on a resource group +resource "azapi_resource" "automation_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.target_resource_group_id}${azapi_resource.automation_account.identity[0].principal_id}contributor") + parent_id = var.target_resource_group_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = azapi_resource.automation_account.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "automation_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.automation_account.id + groupIds = ["DSCAndHybridWorker"] + } + } + ] + } + } + + tags = var.tags +} +``` + +Private DNS zone: `privatelink.azure-automation.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param tags object = {} + +resource automationAccount 'Microsoft.Automation/automationAccounts@2023-11-01' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + sku: { + name: 'Basic' + } + publicNetworkAccess: true + disableLocalAuth: false + encryption: { + keySource: 'Microsoft.Automation' + } + } +} + +output id string = automationAccount.id +output name string = automationAccount.name +output principalId string = automationAccount.identity.principalId +``` + +### With Runbook + +```bicep +param runbookName string +param runbookType string = 'PowerShell72' +param scriptUri string + +resource runbook 'Microsoft.Automation/automationAccounts/runbooks@2023-11-01' = { + parent: automationAccount + name: runbookName + location: location + properties: { + runbookType: runbookType + logProgress: true + logVerbose: false + publishContentLink: { + uri: scriptUri + } + } +} +``` + +### RBAC Assignment + +```bicep +param targetResourceGroupId string + +// Contributor role for automation managed identity +resource contributorRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(targetResourceGroupId, automationAccount.identity.principalId, 'b24988ac-6180-42a0-ab88-20f7382dd24c') + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c') + principalId: automationAccount.identity.principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Using classic Run As accounts | Deprecated since Sept 2023; certificates expire | Use system-assigned managed identity instead | +| Not assigning RBAC to managed identity | Runbooks fail with authorization errors at runtime | Grant appropriate roles to the automation account's identity | +| Free tier job minute limits | Jobs fail after 500 min/month exceeded | Monitor job runtime; upgrade to Basic for production | +| PowerShell version mismatch | Runbook cmdlets behave differently across PS versions | Explicitly specify `PowerShell72` runbook type | +| Storing credentials as Automation variables | Less secure, harder to rotate | Use managed identity or Key Vault references | +| Schedule time zone confusion | Jobs run at unexpected times | Always set `timeZone` explicitly (e.g., "UTC") | +| Not enabling logging on runbooks | Difficult to troubleshoot failed jobs | Set `logProgress = true` and review job streams | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Private endpoint | P1 | Deploy private endpoint and disable public network access | +| Disable local auth | P1 | Set `disableLocalAuth = true` to enforce Entra-only authentication | +| Customer-managed keys | P3 | Enable CMK encryption for automation account data | +| Hybrid runbook workers | P3 | Deploy hybrid workers for on-premises or cross-cloud automation | +| Webhook integration | P3 | Create webhooks for runbooks to enable external triggering | +| Diagnostic settings | P2 | Route automation logs to Log Analytics for monitoring | +| Source control integration | P2 | Connect runbooks to Git for version control and CI/CD | +| Update management | P3 | Enable update management for automated OS patching | diff --git a/azext_prototype/knowledge/services/autoscale-setting.md b/azext_prototype/knowledge/services/autoscale-setting.md new file mode 100644 index 0000000..b825684 --- /dev/null +++ b/azext_prototype/knowledge/services/autoscale-setting.md @@ -0,0 +1,250 @@ +--- +service_namespace: Microsoft.Insights/autoscaleSettings +display_name: Autoscale Setting +--- + +# Autoscale Setting + +> Automatic scaling configuration for Azure resources (App Service Plans, VM Scale Sets, Cloud Services) that adjusts instance count based on metrics, schedules, or both. + +## When to Use +- **App Service Plan scaling** -- automatically add/remove instances based on CPU, memory, or HTTP queue length +- **VM Scale Set scaling** -- scale out/in based on CPU, memory, or custom metrics +- **Schedule-based scaling** -- pre-scale for known traffic patterns (business hours, weekends) +- **Cost optimization** -- scale down during off-peak to reduce costs, scale up during peak to maintain performance + +Autoscale settings are separate resources that attach to a target resource. They are not embedded in the target resource itself. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Default instances | 1 | Minimum for POC | +| Min instances | 1 | Floor for scale-in | +| Max instances | 3 | Cap for scale-out in POC | +| Scale-out metric | CPU > 70% | 5-minute average | +| Scale-in metric | CPU < 30% | 5-minute average | +| Cooldown | 5 minutes | Prevents flapping | +| Enabled | true | Active by default | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "autoscale" { + type = "Microsoft.Insights/autoscaleSettings@2022-10-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enabled = true + targetResourceUri = var.target_resource_id # e.g., App Service Plan ID + profiles = [ + { + name = "default" + capacity = { + default = "1" + minimum = "1" + maximum = "3" + } + rules = [ + { + metricTrigger = { + metricName = "CpuPercentage" + metricResourceUri = var.target_resource_id + timeGrain = "PT1M" + statistic = "Average" + timeWindow = "PT5M" + timeAggregation = "Average" + operator = "GreaterThan" + threshold = 70 + } + scaleAction = { + direction = "Increase" + type = "ChangeCount" + value = "1" + cooldown = "PT5M" + } + }, + { + metricTrigger = { + metricName = "CpuPercentage" + metricResourceUri = var.target_resource_id + timeGrain = "PT1M" + statistic = "Average" + timeWindow = "PT5M" + timeAggregation = "Average" + operator = "LessThan" + threshold = 30 + } + scaleAction = { + direction = "Decrease" + type = "ChangeCount" + value = "1" + cooldown = "PT5M" + } + } + ] + } + ] + notifications = [ + { + operation = "Scale" + email = { + sendToSubscriptionAdministrator = true + sendToSubscriptionCoAdministrators = false + customEmails = var.notification_emails + } + } + ] + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Monitoring Contributor on the target resource for autoscale management +resource "azapi_resource" "monitoring_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.target_resource_id}-${var.principal_id}-monitoring-contributor") + parent_id = var.target_resource_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/749f88d5-cbae-40b8-bcfc-e573ddc772fa" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Autoscale setting name') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Target resource ID (e.g., App Service Plan)') +param targetResourceId string + +@description('Notification email addresses') +param notificationEmails array = [] + +param tags object = {} + +resource autoscale 'Microsoft.Insights/autoscaleSettings@2022-10-01' = { + name: name + location: location + tags: tags + properties: { + enabled: true + targetResourceUri: targetResourceId + profiles: [ + { + name: 'default' + capacity: { + default: '1' + minimum: '1' + maximum: '3' + } + rules: [ + { + metricTrigger: { + metricName: 'CpuPercentage' + metricResourceUri: targetResourceId + timeGrain: 'PT1M' + statistic: 'Average' + timeWindow: 'PT5M' + timeAggregation: 'Average' + operator: 'GreaterThan' + threshold: 70 + } + scaleAction: { + direction: 'Increase' + type: 'ChangeCount' + value: '1' + cooldown: 'PT5M' + } + } + { + metricTrigger: { + metricName: 'CpuPercentage' + metricResourceUri: targetResourceId + timeGrain: 'PT1M' + statistic: 'Average' + timeWindow: 'PT5M' + timeAggregation: 'Average' + operator: 'LessThan' + threshold: 30 + } + scaleAction: { + direction: 'Decrease' + type: 'ChangeCount' + value: '1' + cooldown: 'PT5M' + } + } + ] + } + ] + notifications: [ + { + operation: 'Scale' + email: { + sendToSubscriptionAdministrator: true + sendToSubscriptionCoAdministrators: false + customEmails: notificationEmails + } + } + ] + } +} + +output id string = autoscale.id +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Autoscale manages the number of instances running your application; the application code itself does not need to be aware of scaling events. + +### C# +Infrastructure -- transparent to application code. Autoscale manages the number of instances running your application; the application code itself does not need to be aware of scaling events. + +### Node.js +Infrastructure -- transparent to application code. Autoscale manages the number of instances running your application; the application code itself does not need to be aware of scaling events. + +## Common Pitfalls + +1. **Capacity values are strings** -- `default`, `minimum`, and `maximum` in the capacity block must be strings (e.g., `"1"` not `1`). Numeric values cause deployment errors. +2. **Scale-in and scale-out thresholds** -- Ensure scale-out threshold (e.g., 70%) and scale-in threshold (e.g., 30%) have sufficient gap. Overlapping thresholds cause flapping. +3. **Cooldown too short** -- A cooldown under 5 minutes can cause rapid scaling oscillation. The default 5 minutes is the recommended minimum. +4. **Metric not available on target** -- The `metricName` must exist on the `metricResourceUri`. Using an App Insights metric against an App Service Plan ID fails silently. +5. **Multiple profiles conflict** -- When schedule-based profiles overlap, the first matching profile wins. Order profiles carefully. +6. **Location must match target** -- The autoscale setting must be in the same region as the target resource. +7. **Default profile required** -- At least one profile without a recurrence/schedule is required as the fallback. Omitting it causes unpredictable behavior outside scheduled windows. +8. **Notifications don't include webhooks by default** -- Email is simple but webhook notifications are more actionable. Add webhook URIs for integration with monitoring tools. + +## Production Backlog Items + +- [ ] Tune scale-out/scale-in thresholds based on observed traffic patterns +- [ ] Add schedule-based profiles for known peak/off-peak periods +- [ ] Configure webhook notifications for scaling events +- [ ] Add custom metrics (HTTP queue length, memory) alongside CPU +- [ ] Increase maximum instance count based on capacity requirements +- [ ] Set up Azure Monitor alerts for autoscale failures +- [ ] Test scale-out behavior under load to verify instance readiness time +- [ ] Implement predictive autoscale (preview) for proactive scaling diff --git a/azext_prototype/knowledge/services/azure-ai-search.md b/azext_prototype/knowledge/services/azure-ai-search.md index 907a643..925469e 100644 --- a/azext_prototype/knowledge/services/azure-ai-search.md +++ b/azext_prototype/knowledge/services/azure-ai-search.md @@ -1,358 +1,420 @@ -# Azure AI Search -> Fully managed search-as-a-service with AI enrichment, vector search, and semantic ranking for building rich search experiences over heterogeneous content. - -## When to Use - -- **RAG (Retrieval-Augmented Generation)** -- vector + keyword hybrid search as the retrieval layer for LLM-powered applications -- **Full-text search** -- structured and unstructured content with faceting, filters, scoring profiles -- **Knowledge mining** -- AI enrichment pipelines (skillsets) to extract structure from unstructured documents -- **E-commerce / catalog search** -- autocomplete, suggestions, faceted navigation - -Azure AI Search is the recommended retrieval engine for RAG patterns on Azure. Pair with Azure OpenAI for the generation layer. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | Basic | 2 GiB storage, 3 replicas max; sufficient for POC | -| Replicas | 1 | Scale up for availability SLA | -| Partitions | 1 | Scale up for storage/throughput | -| Semantic ranker | Free tier | 1,000 queries/month free on Basic+ | -| Authentication | API key (POC) | Flag RBAC-only as production backlog item | -| Public network access | Enabled (POC) | Flag private endpoint as production backlog item | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_search_service" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - sku = "basic" - replica_count = 1 - partition_count = 1 - public_network_access_enabled = true # Set false when using private endpoint - local_authentication_enabled = true # Set false when using RBAC-only - - identity { - type = "SystemAssigned" - } - - tags = var.tags -} -``` - -### RBAC Assignment - -```hcl -# Search Index Data Contributor -- allows indexing documents -resource "azurerm_role_assignment" "search_index_contributor" { - scope = azurerm_search_service.this.id - role_definition_name = "Search Index Data Contributor" - principal_id = var.managed_identity_principal_id -} - -# Search Index Data Reader -- allows querying indexes -resource "azurerm_role_assignment" "search_index_reader" { - scope = azurerm_search_service.this.id - role_definition_name = "Search Index Data Reader" - principal_id = var.app_identity_principal_id -} - -# Search Service Contributor -- allows managing indexes, indexers, skillsets -resource "azurerm_role_assignment" "search_service_contributor" { - scope = azurerm_search_service.this.id - role_definition_name = "Search Service Contributor" - principal_id = var.admin_identity_principal_id -} -``` - -RBAC role IDs: -- Search Index Data Reader: `1407120a-92aa-4202-b7e9-c0e197c71c8f` -- Search Index Data Contributor: `8ebe5a00-799e-43f5-93ac-243d3dce84a7` -- Search Service Contributor: `7ca78c08-252a-4471-8644-bb5ff32d4ba0` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "search" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_search_service.this.id - subresource_names = ["searchService"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.search.windows.net` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the search service (globally unique)') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Tags to apply') -param tags object = {} - -resource search 'Microsoft.Search/searchServices@2024-03-01-preview' = { - name: name - location: location - tags: tags - sku: { - name: 'basic' - } - identity: { - type: 'SystemAssigned' - } - properties: { - replicaCount: 1 - partitionCount: 1 - hostingMode: 'default' - publicNetworkAccess: 'enabled' - disableLocalAuth: false // Set true when using RBAC-only - semanticSearch: 'free' - } -} - -output id string = search.id -output name string = search.name -output endpoint string = 'https://${search.name}.search.windows.net' -``` - -### RBAC Assignment - -```bicep -@description('Principal ID for index data operations') -param dataPrincipalId string - -// Search Index Data Contributor role -var searchIndexContributorRoleId = '8ebe5a00-799e-43f5-93ac-243d3dce84a7' - -resource searchRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(search.id, dataPrincipalId, searchIndexContributorRoleId) - scope: search - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', searchIndexContributorRoleId) - principalId: dataPrincipalId - principalType: 'ServicePrincipal' - } -} -``` - -### Private Endpoint - -```bicep -@description('Subnet ID for private endpoint') -param subnetId string = '' - -@description('Private DNS zone ID') -param privateDnsZoneId string = '' - -resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { - name: 'pe-${name}' - location: location - tags: tags - properties: { - subnet: { - id: subnetId - } - privateLinkServiceConnections: [ - { - name: 'psc-${name}' - properties: { - privateLinkServiceId: search.id - groupIds: ['searchService'] - } - } - ] - } -} - -resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = if (!empty(subnetId) && !empty(privateDnsZoneId)) { - parent: privateEndpoint - name: 'dns-zone-group' - properties: { - privateDnsZoneConfigs: [ - { - name: 'config' - properties: { - privateDnsZoneId: privateDnsZoneId - } - } - ] - } -} -``` - -## Application Code - -### Python — Vector Search with Azure OpenAI Embeddings - -```python -from azure.identity import DefaultAzureCredential -from azure.search.documents import SearchClient -from azure.search.documents.indexes import SearchIndexClient -from azure.search.documents.indexes.models import ( - SearchIndex, - SearchField, - SearchFieldDataType, - VectorSearch, - HnswAlgorithmConfiguration, - VectorSearchProfile, - SearchableField, - SimpleField, -) - -credential = DefaultAzureCredential() -endpoint = "https://.search.windows.net" - -# Create index with vector field -index_client = SearchIndexClient(endpoint=endpoint, credential=credential) -index = SearchIndex( - name="documents", - fields=[ - SimpleField(name="id", type=SearchFieldDataType.String, key=True), - SearchableField(name="content", type=SearchFieldDataType.String), - SearchField( - name="embedding", - type=SearchFieldDataType.Collection(SearchFieldDataType.Single), - searchable=True, - vector_search_dimensions=1536, - vector_search_profile_name="default", - ), - ], - vector_search=VectorSearch( - algorithms=[HnswAlgorithmConfiguration(name="hnsw")], - profiles=[VectorSearchProfile(name="default", algorithm_configuration_name="hnsw")], - ), -) -index_client.create_or_update_index(index) - -# Search with vector query -from azure.search.documents.models import VectorizedQuery - -search_client = SearchClient(endpoint=endpoint, index_name="documents", credential=credential) -results = search_client.search( - search_text="user query", # Hybrid: keyword + vector - vector_queries=[ - VectorizedQuery(vector=query_embedding, k_nearest_neighbors=5, fields="embedding") - ], - query_type="semantic", - semantic_configuration_name="default", -) -``` - -### C# — Vector Search - -```csharp -using Azure.Identity; -using Azure.Search.Documents; -using Azure.Search.Documents.Indexes; -using Azure.Search.Documents.Models; - -var credential = new DefaultAzureCredential(); -var endpoint = new Uri("https://.search.windows.net"); - -var searchClient = new SearchClient(endpoint, "documents", credential); - -var options = new SearchOptions -{ - QueryType = SearchQueryType.Semantic, - SemanticSearch = new SemanticSearchOptions - { - SemanticConfigurationName = "default", - }, - VectorSearch = new VectorSearchOptions - { - Queries = { - new VectorizedQuery(queryEmbedding) - { - KNearestNeighborsCount = 5, - Fields = { "embedding" }, - } - } - }, -}; - -SearchResults results = await searchClient.SearchAsync("user query", options); -``` - -### Node.js — Vector Search - -```javascript -const { SearchClient } = require("@azure/search-documents"); -const { DefaultAzureCredential } = require("@azure/identity"); - -const credential = new DefaultAzureCredential(); -const client = new SearchClient( - "https://.search.windows.net", - "documents", - credential -); - -const results = await client.search("user query", { - queryType: "semantic", - semanticSearchOptions: { - configurationName: "default", - }, - vectorSearchOptions: { - queries: [ - { - kind: "vector", - vector: queryEmbedding, - kNearestNeighborsCount: 5, - fields: ["embedding"], - }, - ], - }, -}); -``` - -## Common Pitfalls - -1. **Index schema changes require reindexing** -- Adding new fields is safe, but changing field types or analyzer settings requires deleting and recreating the index. Plan your schema carefully. -2. **Semantic ranker requires Standard tier or higher for production** -- Free tier is limited to 1,000 queries/month. Basic tier supports semantic ranker in free tier only. -3. **Vector dimensions must match embedding model** -- `text-embedding-ada-002` uses 1536 dimensions, `text-embedding-3-small` uses 1536 (default) or 512/256 with dimension reduction. Mismatch causes indexing errors. -4. **RBAC vs API keys** -- New deployments should use RBAC. API keys are simpler for POC but should be flagged for production migration. Set `disableLocalAuth: true` when ready. -5. **Skillset execution costs** -- AI enrichment (OCR, entity recognition, etc.) incurs Cognitive Services charges on top of search costs. Monitor carefully. -6. **Integrated vectorization vs push model** -- Integrated vectorization (preview) auto-generates embeddings during indexing. Push model requires you to generate embeddings before uploading. Push model is more mature. -7. **Indexer data source connection** -- When using indexers with Blob Storage or SQL, the search service needs network access to the data source. Private endpoints on both sides require shared private link. - -## Production Backlog Items - -- [ ] Switch from API key to RBAC-only authentication (`disableLocalAuth: true`) -- [ ] Enable private endpoint and disable public network access -- [ ] Configure shared private links for indexer data source access -- [ ] Upgrade to Standard tier for production semantic ranker quota -- [ ] Add replica for 99.9% availability SLA (2+ replicas required) -- [ ] Configure diagnostic settings for query analytics -- [ ] Implement index aliases for zero-downtime schema changes -- [ ] Set up scheduled indexer refresh for data source synchronization -- [ ] Configure custom analyzers for domain-specific content -- [ ] Add geo-redundancy if multi-region availability is needed +--- +service_namespace: Microsoft.Search/searchServices +display_name: Azure AI Search +--- + +# Azure AI Search +> Fully managed search-as-a-service with AI enrichment, vector search, and semantic ranking for building rich search experiences over heterogeneous content. + +## When to Use + +- **RAG (Retrieval-Augmented Generation)** -- vector + keyword hybrid search as the retrieval layer for LLM-powered applications +- **Full-text search** -- structured and unstructured content with faceting, filters, scoring profiles +- **Knowledge mining** -- AI enrichment pipelines (skillsets) to extract structure from unstructured documents +- **E-commerce / catalog search** -- autocomplete, suggestions, faceted navigation + +Azure AI Search is the recommended retrieval engine for RAG patterns on Azure. Pair with Azure OpenAI for the generation layer. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | 2 GiB storage, 3 replicas max; sufficient for POC | +| Replicas | 1 | Scale up for availability SLA | +| Partitions | 1 | Scale up for storage/throughput | +| Semantic ranker | Free tier | 1,000 queries/month free on Basic+ | +| Authentication | API key (POC) | Flag RBAC-only as production backlog item | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "search" { + type = "Microsoft.Search/searchServices@2024-03-01-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "basic" + } + properties = { + replicaCount = 1 + partitionCount = 1 + hostingMode = "default" + publicNetworkAccess = "disabled" # Unless told otherwise, disabled per governance policy + disableLocalAuth = false # Set true when using RBAC-only + semanticSearch = "free" + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### RBAC Assignment + +```hcl +# Search Index Data Contributor -- allows indexing documents +resource "azapi_resource" "search_index_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.search.id}${var.managed_identity_principal_id}index-contributor") + parent_id = azapi_resource.search.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7" # Search Index Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Search Index Data Reader -- allows querying indexes +resource "azapi_resource" "search_index_reader_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.search.id}${var.app_identity_principal_id}index-reader") + parent_id = azapi_resource.search.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f" # Search Index Data Reader + principalId = var.app_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Search Service Contributor -- allows managing indexes, indexers, skillsets +resource "azapi_resource" "search_service_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.search.id}${var.admin_identity_principal_id}svc-contributor") + parent_id = azapi_resource.search.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/7ca78c08-252a-4471-8644-bb5ff32d4ba0" # Search Service Contributor + principalId = var.admin_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +RBAC role IDs: +- Search Index Data Reader: `1407120a-92aa-4202-b7e9-c0e197c71c8f` +- Search Index Data Contributor: `8ebe5a00-799e-43f5-93ac-243d3dce84a7` +- Search Service Contributor: `7ca78c08-252a-4471-8644-bb5ff32d4ba0` + +### Private Endpoint + +```hcl +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.search.id + groupIds = ["searchService"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.search.windows.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the search service (globally unique)') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource search 'Microsoft.Search/searchServices@2024-03-01-preview' = { + name: name + location: location + tags: tags + sku: { + name: 'basic' + } + identity: { + type: 'SystemAssigned' + } + properties: { + replicaCount: 1 + partitionCount: 1 + hostingMode: 'default' + publicNetworkAccess: 'enabled' + disableLocalAuth: false // Set true when using RBAC-only + semanticSearch: 'free' + } +} + +output id string = search.id +output name string = search.name +output endpoint string = 'https://${search.name}.search.windows.net' +``` + +### RBAC Assignment + +```bicep +@description('Principal ID for index data operations') +param dataPrincipalId string + +// Search Index Data Contributor role +var searchIndexContributorRoleId = '8ebe5a00-799e-43f5-93ac-243d3dce84a7' + +resource searchRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(search.id, dataPrincipalId, searchIndexContributorRoleId) + scope: search + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', searchIndexContributorRoleId) + principalId: dataPrincipalId + principalType: 'ServicePrincipal' + } +} +``` + +### Private Endpoint + +```bicep +@description('Subnet ID for private endpoint') +param subnetId string = '' + +@description('Private DNS zone ID') +param privateDnsZoneId string = '' + +resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { + name: 'pe-${name}' + location: location + tags: tags + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'psc-${name}' + properties: { + privateLinkServiceId: search.id + groupIds: ['searchService'] + } + } + ] + } +} + +resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = if (!empty(subnetId) && !empty(privateDnsZoneId)) { + parent: privateEndpoint + name: 'dns-zone-group' + properties: { + privateDnsZoneConfigs: [ + { + name: 'config' + properties: { + privateDnsZoneId: privateDnsZoneId + } + } + ] + } +} +``` + +## Application Code + +### Python — Vector Search with Azure OpenAI Embeddings + +```python +from azure.identity import DefaultAzureCredential +from azure.search.documents import SearchClient +from azure.search.documents.indexes import SearchIndexClient +from azure.search.documents.indexes.models import ( + SearchIndex, + SearchField, + SearchFieldDataType, + VectorSearch, + HnswAlgorithmConfiguration, + VectorSearchProfile, + SearchableField, + SimpleField, +) + +credential = DefaultAzureCredential() +endpoint = "https://.search.windows.net" + +# Create index with vector field +index_client = SearchIndexClient(endpoint=endpoint, credential=credential) +index = SearchIndex( + name="documents", + fields=[ + SimpleField(name="id", type=SearchFieldDataType.String, key=True), + SearchableField(name="content", type=SearchFieldDataType.String), + SearchField( + name="embedding", + type=SearchFieldDataType.Collection(SearchFieldDataType.Single), + searchable=True, + vector_search_dimensions=1536, + vector_search_profile_name="default", + ), + ], + vector_search=VectorSearch( + algorithms=[HnswAlgorithmConfiguration(name="hnsw")], + profiles=[VectorSearchProfile(name="default", algorithm_configuration_name="hnsw")], + ), +) +index_client.create_or_update_index(index) + +# Search with vector query +from azure.search.documents.models import VectorizedQuery + +search_client = SearchClient(endpoint=endpoint, index_name="documents", credential=credential) +results = search_client.search( + search_text="user query", # Hybrid: keyword + vector + vector_queries=[ + VectorizedQuery(vector=query_embedding, k_nearest_neighbors=5, fields="embedding") + ], + query_type="semantic", + semantic_configuration_name="default", +) +``` + +### C# — Vector Search + +```csharp +using Azure.Identity; +using Azure.Search.Documents; +using Azure.Search.Documents.Indexes; +using Azure.Search.Documents.Models; + +var credential = new DefaultAzureCredential(); +var endpoint = new Uri("https://.search.windows.net"); + +var searchClient = new SearchClient(endpoint, "documents", credential); + +var options = new SearchOptions +{ + QueryType = SearchQueryType.Semantic, + SemanticSearch = new SemanticSearchOptions + { + SemanticConfigurationName = "default", + }, + VectorSearch = new VectorSearchOptions + { + Queries = { + new VectorizedQuery(queryEmbedding) + { + KNearestNeighborsCount = 5, + Fields = { "embedding" }, + } + } + }, +}; + +SearchResults results = await searchClient.SearchAsync("user query", options); +``` + +### Node.js — Vector Search + +```javascript +const { SearchClient } = require("@azure/search-documents"); +const { DefaultAzureCredential } = require("@azure/identity"); + +const credential = new DefaultAzureCredential(); +const client = new SearchClient( + "https://.search.windows.net", + "documents", + credential +); + +const results = await client.search("user query", { + queryType: "semantic", + semanticSearchOptions: { + configurationName: "default", + }, + vectorSearchOptions: { + queries: [ + { + kind: "vector", + vector: queryEmbedding, + kNearestNeighborsCount: 5, + fields: ["embedding"], + }, + ], + }, +}); +``` + +## Common Pitfalls + +1. **Index schema changes require reindexing** -- Adding new fields is safe, but changing field types or analyzer settings requires deleting and recreating the index. Plan your schema carefully. +2. **Semantic ranker requires Standard tier or higher for production** -- Free tier is limited to 1,000 queries/month. Basic tier supports semantic ranker in free tier only. +3. **Vector dimensions must match embedding model** -- `text-embedding-ada-002` uses 1536 dimensions, `text-embedding-3-small` uses 1536 (default) or 512/256 with dimension reduction. Mismatch causes indexing errors. +4. **RBAC vs API keys** -- New deployments should use RBAC. API keys are simpler for POC but should be flagged for production migration. Set `disableLocalAuth: true` when ready. +5. **Skillset execution costs** -- AI enrichment (OCR, entity recognition, etc.) incurs Cognitive Services charges on top of search costs. Monitor carefully. +6. **Integrated vectorization vs push model** -- Integrated vectorization (preview) auto-generates embeddings during indexing. Push model requires you to generate embeddings before uploading. Push model is more mature. +7. **Indexer data source connection** -- When using indexers with Blob Storage or SQL, the search service needs network access to the data source. Private endpoints on both sides require shared private link. + +## Production Backlog Items + +- [ ] Switch from API key to RBAC-only authentication (`disableLocalAuth: true`) +- [ ] Enable private endpoint and disable public network access +- [ ] Configure shared private links for indexer data source access +- [ ] Upgrade to Standard tier for production semantic ranker quota +- [ ] Add replica for 99.9% availability SLA (2+ replicas required) +- [ ] Configure diagnostic settings for query analytics +- [ ] Implement index aliases for zero-downtime schema changes +- [ ] Set up scheduled indexer refresh for data source synchronization +- [ ] Configure custom analyzers for domain-specific content +- [ ] Add geo-redundancy if multi-region availability is needed diff --git a/azext_prototype/knowledge/services/azure-functions.md b/azext_prototype/knowledge/services/azure-functions.md index 7060621..8a28ebb 100644 --- a/azext_prototype/knowledge/services/azure-functions.md +++ b/azext_prototype/knowledge/services/azure-functions.md @@ -1,428 +1,558 @@ -# Azure Functions -> Event-driven serverless compute platform for running code on-demand without managing infrastructure, supporting multiple languages and trigger types. - -## When to Use - -- Event-driven processing (HTTP requests, queue messages, timer-based jobs, blob triggers) -- Lightweight APIs with sporadic or unpredictable traffic patterns -- Background processing and data transformation tasks -- Integrations between Azure services (e.g., Service Bus to Cosmos DB) -- Microservice endpoints that scale independently -- NOT suitable for: long-running processes over 10 minutes (use Container Apps or Durable Functions), stateful workloads requiring persistent connections, or applications needing full control over the hosting environment - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Plan | Consumption (Y1) | Flex Consumption for preview features; B1 App Service Plan if VNet needed | -| OS | Linux | Preferred for Python/Node; Windows for .NET in-process | -| Runtime | Python 3.12 / Node 20 / .NET 8 (isolated) | Match project requirements | -| HTTPS Only | true | Enforced by policy | -| Minimum TLS | 1.2 | Enforced by policy | -| Managed identity | User-assigned | Attached to the function app | -| Storage account | Required | Separate from any data storage; used for runtime state (AzureWebJobsStorage) | - -**CRITICAL**: Azure Functions REQUIRE a dedicated storage account for internal runtime operations (function triggers, bindings state, task hub for Durable Functions). This storage account is separate from any application data storage and must always be provisioned alongside the function app. - -## Terraform Patterns - -### Basic Resource - -```hcl -# Storage account required for Functions runtime -resource "azurerm_storage_account" "functions" { - name = var.storage_account_name - location = var.location - resource_group_name = var.resource_group_name - account_tier = "Standard" - account_replication_type = "LRS" - min_tls_version = "TLS1_2" - - tags = var.tags -} - -# Consumption plan -resource "azurerm_service_plan" "this" { - name = var.plan_name - location = var.location - resource_group_name = var.resource_group_name - os_type = "Linux" - sku_name = "Y1" # Consumption plan - - tags = var.tags -} - -resource "azurerm_linux_function_app" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - service_plan_id = azurerm_service_plan.this.id - storage_account_name = azurerm_storage_account.functions.name - storage_account_access_key = azurerm_storage_account.functions.primary_access_key - https_only = true - - identity { - type = "UserAssigned" - identity_ids = [var.managed_identity_id] - } - - site_config { - minimum_tls_version = "1.2" - - application_stack { - python_version = "3.12" # or node_version, dotnet_version - } - } - - app_settings = merge(var.app_settings, { - "AZURE_CLIENT_ID" = var.managed_identity_client_id - "FUNCTIONS_WORKER_RUNTIME" = "python" # or "node", "dotnet-isolated" - "AzureWebJobsFeatureFlags" = "EnableWorkerIndexing" - }) - - tags = var.tags -} -``` - -### Storage Account with Managed Identity (preferred over access keys) - -```hcl -# When using managed identity for the functions storage connection: -resource "azurerm_linux_function_app" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - service_plan_id = azurerm_service_plan.this.id - storage_account_name = azurerm_storage_account.functions.name - storage_uses_managed_identity = true - https_only = true - - identity { - type = "UserAssigned" - identity_ids = [var.managed_identity_id] - } - - site_config { - minimum_tls_version = "1.2" - - application_stack { - python_version = "3.12" - } - } - - app_settings = merge(var.app_settings, { - "AZURE_CLIENT_ID" = var.managed_identity_client_id - "AzureWebJobsStorage__accountName" = azurerm_storage_account.functions.name - "AzureWebJobsStorage__credential" = "managedidentity" - "AzureWebJobsStorage__clientId" = var.managed_identity_client_id - }) - - tags = var.tags -} - -# Grant the function app's identity Storage Blob Data Owner on its runtime storage -resource "azurerm_role_assignment" "functions_storage" { - scope = azurerm_storage_account.functions.id - role_definition_name = "Storage Blob Data Owner" - principal_id = var.managed_identity_principal_id -} - -resource "azurerm_role_assignment" "functions_storage_queue" { - scope = azurerm_storage_account.functions.id - role_definition_name = "Storage Queue Data Contributor" - principal_id = var.managed_identity_principal_id -} - -resource "azurerm_role_assignment" "functions_storage_table" { - scope = azurerm_storage_account.functions.id - role_definition_name = "Storage Table Data Contributor" - principal_id = var.managed_identity_principal_id -} -``` - -### RBAC Assignment - -```hcl -# Function app's managed identity accessing other resources -# Example: grant access to Service Bus for queue-triggered functions -resource "azurerm_role_assignment" "servicebus_receiver" { - scope = var.servicebus_namespace_id - role_definition_name = "Azure Service Bus Data Receiver" - principal_id = var.managed_identity_principal_id -} - -resource "azurerm_role_assignment" "servicebus_sender" { - scope = var.servicebus_namespace_id - role_definition_name = "Azure Service Bus Data Sender" - principal_id = var.managed_identity_principal_id -} -``` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "this" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_linux_function_app.this.id - subresource_names = ["sites"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -## Bicep Patterns - -### Basic Resource - -```bicep -param name string -param location string -param planName string -param storageAccountName string -param managedIdentityId string -param managedIdentityClientId string -param runtime string = 'python' -param runtimeVersion string = '3.12' -param tags object = {} - -resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { - name: storageAccountName - location: location - kind: 'StorageV2' - sku: { - name: 'Standard_LRS' - } - properties: { - minimumTlsVersion: 'TLS1_2' - supportsHttpsTrafficOnly: true - } - tags: tags -} - -resource hostingPlan 'Microsoft.Web/serverfarms@2023-12-01' = { - name: planName - location: location - kind: 'linux' - sku: { - name: 'Y1' - tier: 'Dynamic' - } - properties: { - reserved: true - } - tags: tags -} - -resource functionApp 'Microsoft.Web/sites@2023-12-01' = { - name: name - location: location - kind: 'functionapp,linux' - identity: { - type: 'UserAssigned' - userAssignedIdentities: { - '${managedIdentityId}': {} - } - } - properties: { - serverFarmId: hostingPlan.id - httpsOnly: true - siteConfig: { - minTlsVersion: '1.2' - linuxFxVersion: '${toUpper(runtime)}|${runtimeVersion}' - appSettings: [ - { - name: 'AzureWebJobsStorage' - value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};EndpointSuffix=${environment().suffixes.storage};AccountKey=${storageAccount.listKeys().keys[0].value}' - } - { - name: 'FUNCTIONS_EXTENSION_VERSION' - value: '~4' - } - { - name: 'FUNCTIONS_WORKER_RUNTIME' - value: runtime - } - { - name: 'AZURE_CLIENT_ID' - value: managedIdentityClientId - } - ] - } - } - tags: tags -} - -output id string = functionApp.id -output name string = functionApp.name -output defaultHostName string = functionApp.properties.defaultHostName -``` - -### RBAC Assignment - -```bicep -param principalId string -param serviceBusNamespaceId string - -resource sbReceiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(serviceBusNamespaceId, principalId, '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0') - scope: serviceBusNamespace - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0') // Azure Service Bus Data Receiver - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python (Azure Functions v2 programming model) - -```python -import os -import logging -import azure.functions as func -from azure.identity import ManagedIdentityCredential, DefaultAzureCredential - -app = func.FunctionApp() - -def get_credential(): - client_id = os.getenv("AZURE_CLIENT_ID") - if client_id: - return ManagedIdentityCredential(client_id=client_id) - return DefaultAzureCredential() - -@app.function_name(name="HttpTrigger") -@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS) -def hello(req: func.HttpRequest) -> func.HttpResponse: - name = req.params.get("name", "World") - return func.HttpResponse(f"Hello, {name}!") - -@app.function_name(name="QueueTrigger") -@app.queue_trigger(arg_name="msg", queue_name="my-queue", - connection="AzureWebJobsStorage") -def process_queue(msg: func.QueueMessage) -> None: - logging.info(f"Processing message: {msg.get_body().decode('utf-8')}") - -@app.function_name(name="TimerTrigger") -@app.timer_trigger(schedule="0 */5 * * * *", arg_name="timer", - run_on_startup=False) -def timer_job(timer: func.TimerRequest) -> None: - logging.info("Timer trigger executed") -``` - -### C# (.NET 8 Isolated Worker) - -```csharp -using Azure.Identity; -using Microsoft.Azure.Functions.Worker; -using Microsoft.Azure.Functions.Worker.Http; -using Microsoft.Extensions.Hosting; -using Microsoft.Extensions.DependencyInjection; -using System.Net; - -var host = new HostBuilder() - .ConfigureFunctionsWorkerDefaults() - .ConfigureServices(services => - { - var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); - services.AddSingleton(sp => - string.IsNullOrEmpty(clientId) - ? new DefaultAzureCredential() - : new ManagedIdentityCredential(clientId)); - }) - .Build(); - -host.Run(); - -// Functions/HelloFunction.cs -public class HelloFunction -{ - [Function("HttpTrigger")] - public HttpResponseData Run( - [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequestData req) - { - var response = req.CreateResponse(HttpStatusCode.OK); - response.WriteString("Hello from Azure Functions!"); - return response; - } -} -``` - -### Node.js (Azure Functions v4 programming model) - -```javascript -const { app } = require("@azure/functions"); -const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); - -function getCredential() { - const clientId = process.env.AZURE_CLIENT_ID; - return clientId - ? new ManagedIdentityCredential(clientId) - : new DefaultAzureCredential(); -} - -app.http("hello", { - methods: ["GET"], - authLevel: "anonymous", - handler: async (request, context) => { - const name = request.query.get("name") || "World"; - return { body: `Hello, ${name}!` }; - }, -}); - -app.serviceBusQueue("processQueue", { - queueName: "my-queue", - connection: "ServiceBusConnection", - handler: async (message, context) => { - context.log("Processing message:", message); - }, -}); -``` - -## Common Pitfalls - -| Pitfall | Impact | Prevention | -|---------|--------|-----------| -| Forgetting the runtime storage account | Function app fails to start | Always provision a dedicated storage account for the function runtime | -| Using the same storage account for runtime and data | Lock contention, unexpected behavior | Use separate storage accounts for runtime (AzureWebJobsStorage) and application data | -| Consumption plan + VNet integration | Not supported on Consumption plan | Use Flex Consumption, Premium (EP1+), or dedicated App Service Plan for VNet integration | -| Cold start latency on Consumption plan | First request after idle takes seconds | Accept for POC; use Premium plan or pre-warmed instances for production | -| Wrong `FUNCTIONS_WORKER_RUNTIME` | Functions fail to load | Must match the deployed runtime: `python`, `node`, `dotnet-isolated` | -| Missing `FUNCTIONS_EXTENSION_VERSION` | Defaults to older runtime | Always set to `~4` for Functions v4 | -| Python v1 vs v2 programming model | Code structure incompatibility | Use v2 programming model (decorator-based) for new projects | -| Durable Functions without proper storage | Orchestrations hang or fail | Durable Functions require the runtime storage account with table and queue access | -| HTTP trigger with AuthLevel.Function but no key management | Unauthorized access | Use `Anonymous` for POC behind APIM, or `Function` with keys for direct access | - -## Production Backlog Items - -| Item | Priority | Description | -|------|----------|-------------| -| Premium plan (EP1+) | P1 | Upgrade to Premium plan for VNet integration and private endpoints | -| Dedicated storage account | P2 | Ensure runtime storage is isolated from application data storage | -| VNet integration | P1 | Enable VNet integration for outbound traffic to private endpoints | -| Private endpoint (inbound) | P1 | Add private endpoint if functions should not be publicly accessible | -| CORS configuration | P3 | Configure allowed origins for browser-based consumers | -| Function app slots | P2 | Configure staging slot for zero-downtime deployments | -| Application Insights integration | P3 | Enable distributed tracing and performance monitoring | -| Managed identity for storage | P2 | Replace storage account access key with managed identity connection | -| Scale limits | P3 | Configure maximum instance count to control costs | -| IP restrictions | P1 | Restrict inbound access to known IP ranges or APIM/Front Door only | +--- +service_namespace: Microsoft.Web/sites#functionapp +display_name: Azure Functions +depends_on: + - Microsoft.Web/serverfarms +--- + +# Azure Functions +> Event-driven serverless compute platform for running code on-demand without managing infrastructure, supporting multiple languages and trigger types. + +## When to Use + +- Event-driven processing (HTTP requests, queue messages, timer-based jobs, blob triggers) +- Lightweight APIs with sporadic or unpredictable traffic patterns +- Background processing and data transformation tasks +- Integrations between Azure services (e.g., Service Bus to Cosmos DB) +- Microservice endpoints that scale independently +- NOT suitable for: long-running processes over 10 minutes (use Container Apps or Durable Functions), stateful workloads requiring persistent connections, or applications needing full control over the hosting environment + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Plan | Consumption (Y1) | Flex Consumption for preview features; B1 App Service Plan if VNet needed | +| OS | Linux | Preferred for Python/Node; Windows for .NET in-process | +| Runtime | Python 3.12 / Node 20 / .NET 8 (isolated) | Match project requirements | +| HTTPS Only | true | Enforced by policy | +| Minimum TLS | 1.2 | Enforced by policy | +| Managed identity | User-assigned | Attached to the function app | +| Storage account | Required | Separate from any data storage; used for runtime state (AzureWebJobsStorage) | + +**CRITICAL**: Azure Functions REQUIRE a dedicated storage account for internal runtime operations (function triggers, bindings state, task hub for Durable Functions). This storage account is separate from any application data storage and must always be provisioned alongside the function app. + +## Terraform Patterns + +### Basic Resource + +```hcl +# Storage account required for Functions runtime +resource "azapi_resource" "functions_storage" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.storage_account_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "StorageV2" + sku = { + name = "Standard_LRS" + } + properties = { + minimumTlsVersion = "TLS1_2" + supportsHttpsTrafficOnly = true + } + } + + tags = var.tags + + response_export_values = ["properties.primaryEndpoints", "id"] +} + +# Consumption plan +resource "azapi_resource" "plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "linux" + sku = { + name = "Y1" # Consumption plan + tier = "Dynamic" + } + properties = { + reserved = true + } + } + + tags = var.tags +} + +resource "azapi_resource" "function_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + kind = "functionapp,linux" + properties = { + serverFarmId = azapi_resource.plan.id + httpsOnly = true + siteConfig = { + minTlsVersion = "1.2" + linuxFxVersion = "PYTHON|3.12" # or NODE|20, DOTNET-ISOLATED|8.0 + appSettings = [ + { + name = "AzureWebJobsStorage" + value = "DefaultEndpointsProtocol=https;AccountName=${var.storage_account_name};AccountKey=${data.azapi_resource_action.storage_keys.output.keys[0].value};EndpointSuffix=core.windows.net" + }, + { + name = "FUNCTIONS_EXTENSION_VERSION" + value = "~4" + }, + { + name = "FUNCTIONS_WORKER_RUNTIME" + value = "python" # or "node", "dotnet-isolated" + }, + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + }, + { + name = "AzureWebJobsFeatureFlags" + value = "EnableWorkerIndexing" + } + ] + } + } + } + + tags = var.tags + + response_export_values = ["properties.defaultHostName"] +} +``` + +### Storage Account with Managed Identity (preferred over access keys) + +```hcl +# When using managed identity for the functions storage connection: +resource "azapi_resource" "function_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + kind = "functionapp,linux" + properties = { + serverFarmId = azapi_resource.plan.id + httpsOnly = true + siteConfig = { + minTlsVersion = "1.2" + linuxFxVersion = "PYTHON|3.12" + appSettings = [ + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + }, + { + name = "AzureWebJobsStorage__accountName" + value = var.storage_account_name + }, + { + name = "AzureWebJobsStorage__credential" + value = "managedidentity" + }, + { + name = "AzureWebJobsStorage__clientId" + value = var.managed_identity_client_id + }, + { + name = "FUNCTIONS_EXTENSION_VERSION" + value = "~4" + }, + { + name = "FUNCTIONS_WORKER_RUNTIME" + value = "python" + } + ] + } + } + } + + tags = var.tags + + response_export_values = ["properties.defaultHostName"] +} + +# Grant the function app's identity Storage Blob Data Owner on its runtime storage +resource "azapi_resource" "functions_storage_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.functions_storage.id}${var.managed_identity_principal_id}blob-owner") + parent_id = azapi_resource.functions_storage.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b7e6dc6d-f1e8-4753-8033-0f276bb0955b" # Storage Blob Data Owner + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +resource "azapi_resource" "functions_storage_queue_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.functions_storage.id}${var.managed_identity_principal_id}queue-contributor") + parent_id = azapi_resource.functions_storage.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/974c5e8b-45b9-4653-ba55-5f855dd0fb88" # Storage Queue Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +resource "azapi_resource" "functions_storage_table_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.functions_storage.id}${var.managed_identity_principal_id}table-contributor") + parent_id = azapi_resource.functions_storage.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3" # Storage Table Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### RBAC Assignment + +```hcl +# Function app's managed identity accessing other resources +# Example: grant access to Service Bus for queue-triggered functions +resource "azapi_resource" "servicebus_receiver_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.servicebus_namespace_id}${var.managed_identity_principal_id}sb-receiver") + parent_id = var.servicebus_namespace_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0" # Azure Service Bus Data Receiver + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +resource "azapi_resource" "servicebus_sender_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.servicebus_namespace_id}${var.managed_identity_principal_id}sb-sender") + parent_id = var.servicebus_namespace_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/69a216fc-b8fb-44d8-bc22-1f3c2cd27a39" # Azure Service Bus Data Sender + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.function_app.id + groupIds = ["sites"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param planName string +param storageAccountName string +param managedIdentityId string +param managedIdentityClientId string +param runtime string = 'python' +param runtimeVersion string = '3.12' +param tags object = {} + +resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = { + name: storageAccountName + location: location + kind: 'StorageV2' + sku: { + name: 'Standard_LRS' + } + properties: { + minimumTlsVersion: 'TLS1_2' + supportsHttpsTrafficOnly: true + } + tags: tags +} + +resource hostingPlan 'Microsoft.Web/serverfarms@2023-12-01' = { + name: planName + location: location + kind: 'linux' + sku: { + name: 'Y1' + tier: 'Dynamic' + } + properties: { + reserved: true + } + tags: tags +} + +resource functionApp 'Microsoft.Web/sites@2023-12-01' = { + name: name + location: location + kind: 'functionapp,linux' + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + properties: { + serverFarmId: hostingPlan.id + httpsOnly: true + siteConfig: { + minTlsVersion: '1.2' + linuxFxVersion: '${toUpper(runtime)}|${runtimeVersion}' + appSettings: [ + { + name: 'AzureWebJobsStorage' + value: 'DefaultEndpointsProtocol=https;AccountName=${storageAccount.name};EndpointSuffix=${environment().suffixes.storage};AccountKey=${storageAccount.listKeys().keys[0].value}' + } + { + name: 'FUNCTIONS_EXTENSION_VERSION' + value: '~4' + } + { + name: 'FUNCTIONS_WORKER_RUNTIME' + value: runtime + } + { + name: 'AZURE_CLIENT_ID' + value: managedIdentityClientId + } + ] + } + } + tags: tags +} + +output id string = functionApp.id +output name string = functionApp.name +output defaultHostName string = functionApp.properties.defaultHostName +``` + +### RBAC Assignment + +```bicep +param principalId string +param serviceBusNamespaceId string + +resource sbReceiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(serviceBusNamespaceId, principalId, '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0') + scope: serviceBusNamespace + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4f6d3b9b-027b-4f4c-9142-0e5a2a2247e0') // Azure Service Bus Data Receiver + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python (Azure Functions v2 programming model) + +```python +import os +import logging +import azure.functions as func +from azure.identity import ManagedIdentityCredential, DefaultAzureCredential + +app = func.FunctionApp() + +def get_credential(): + client_id = os.getenv("AZURE_CLIENT_ID") + if client_id: + return ManagedIdentityCredential(client_id=client_id) + return DefaultAzureCredential() + +@app.function_name(name="HttpTrigger") +@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS) +def hello(req: func.HttpRequest) -> func.HttpResponse: + name = req.params.get("name", "World") + return func.HttpResponse(f"Hello, {name}!") + +@app.function_name(name="QueueTrigger") +@app.queue_trigger(arg_name="msg", queue_name="my-queue", + connection="AzureWebJobsStorage") +def process_queue(msg: func.QueueMessage) -> None: + logging.info(f"Processing message: {msg.get_body().decode('utf-8')}") + +@app.function_name(name="TimerTrigger") +@app.timer_trigger(schedule="0 */5 * * * *", arg_name="timer", + run_on_startup=False) +def timer_job(timer: func.TimerRequest) -> None: + logging.info("Timer trigger executed") +``` + +### C# (.NET 8 Isolated Worker) + +```csharp +using Azure.Identity; +using Microsoft.Azure.Functions.Worker; +using Microsoft.Azure.Functions.Worker.Http; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.DependencyInjection; +using System.Net; + +var host = new HostBuilder() + .ConfigureFunctionsWorkerDefaults() + .ConfigureServices(services => + { + var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); + services.AddSingleton(sp => + string.IsNullOrEmpty(clientId) + ? new DefaultAzureCredential() + : new ManagedIdentityCredential(clientId)); + }) + .Build(); + +host.Run(); + +// Functions/HelloFunction.cs +public class HelloFunction +{ + [Function("HttpTrigger")] + public HttpResponseData Run( + [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequestData req) + { + var response = req.CreateResponse(HttpStatusCode.OK); + response.WriteString("Hello from Azure Functions!"); + return response; + } +} +``` + +### Node.js (Azure Functions v4 programming model) + +```javascript +const { app } = require("@azure/functions"); +const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); + +function getCredential() { + const clientId = process.env.AZURE_CLIENT_ID; + return clientId + ? new ManagedIdentityCredential(clientId) + : new DefaultAzureCredential(); +} + +app.http("hello", { + methods: ["GET"], + authLevel: "anonymous", + handler: async (request, context) => { + const name = request.query.get("name") || "World"; + return { body: `Hello, ${name}!` }; + }, +}); + +app.serviceBusQueue("processQueue", { + queueName: "my-queue", + connection: "ServiceBusConnection", + handler: async (message, context) => { + context.log("Processing message:", message); + }, +}); +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Forgetting the runtime storage account | Function app fails to start | Always provision a dedicated storage account for the function runtime | +| Using the same storage account for runtime and data | Lock contention, unexpected behavior | Use separate storage accounts for runtime (AzureWebJobsStorage) and application data | +| Consumption plan + VNet integration | Not supported on Consumption plan | Use Flex Consumption, Premium (EP1+), or dedicated App Service Plan for VNet integration | +| Cold start latency on Consumption plan | First request after idle takes seconds | Accept for POC; use Premium plan or pre-warmed instances for production | +| Wrong `FUNCTIONS_WORKER_RUNTIME` | Functions fail to load | Must match the deployed runtime: `python`, `node`, `dotnet-isolated` | +| Missing `FUNCTIONS_EXTENSION_VERSION` | Defaults to older runtime | Always set to `~4` for Functions v4 | +| Python v1 vs v2 programming model | Code structure incompatibility | Use v2 programming model (decorator-based) for new projects | +| Durable Functions without proper storage | Orchestrations hang or fail | Durable Functions require the runtime storage account with table and queue access | +| HTTP trigger with AuthLevel.Function but no key management | Unauthorized access | Use `Anonymous` for POC behind APIM, or `Function` with keys for direct access | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Premium plan (EP1+) | P1 | Upgrade to Premium plan for VNet integration and private endpoints | +| Dedicated storage account | P2 | Ensure runtime storage is isolated from application data storage | +| VNet integration | P1 | Enable VNet integration for outbound traffic to private endpoints | +| Private endpoint (inbound) | P1 | Add private endpoint if functions should not be publicly accessible | +| CORS configuration | P3 | Configure allowed origins for browser-based consumers | +| Function app slots | P2 | Configure staging slot for zero-downtime deployments | +| Application Insights integration | P3 | Enable distributed tracing and performance monitoring | +| Managed identity for storage | P2 | Replace storage account access key with managed identity connection | +| Scale limits | P3 | Configure maximum instance count to control costs | +| IP restrictions | P1 | Restrict inbound access to known IP ranges or APIM/Front Door only | diff --git a/azext_prototype/knowledge/services/azure-openai.md b/azext_prototype/knowledge/services/azure-openai.md new file mode 100644 index 0000000..f6c6518 --- /dev/null +++ b/azext_prototype/knowledge/services/azure-openai.md @@ -0,0 +1,262 @@ +--- +service_namespace: Microsoft.CognitiveServices/accounts +display_name: Azure OpenAI Service +--- + +# Azure OpenAI Service +> Managed deployment of OpenAI language models (GPT-4o, GPT-4, GPT-3.5, DALL-E, Whisper, text-embedding) with Azure enterprise security, compliance, and regional availability. + +## When to Use + +- **Conversational AI** -- chatbots, virtual assistants, customer support automation +- **Content generation** -- summarization, translation, document drafting, code generation +- **RAG (Retrieval-Augmented Generation)** -- combine with Azure AI Search for grounded answers from your data +- **Embeddings** -- semantic search, document similarity, clustering, recommendations +- **Image generation** -- DALL-E for creative and design workflows +- **Audio transcription** -- Whisper for speech-to-text + +Prefer Azure OpenAI over direct OpenAI API when you need: data residency guarantees, VNet/private endpoint access, Azure RBAC, content filtering, or integration with Azure AI Search for on-your-data scenarios. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Account kind | OpenAI | `kind = "OpenAI"` on Cognitive Services account | +| SKU | S0 | Standard tier; only option for OpenAI | +| Model | gpt-4o (2024-08-06) | Best quality/cost balance for POC | +| Embedding model | text-embedding-3-small | Lower cost than large variant | +| Deployment type | Standard | Global-Standard for higher rate limits | +| Tokens per minute | 10K-30K TPM | Start low for POC; increase as needed | +| Content filter | Default | Microsoft managed; customize if needed | +| Authentication | AAD (RBAC) | Disable API keys when possible | +| Public network access | Enabled | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "openai" { + type = "Microsoft.CognitiveServices/accounts@2024-04-01-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "OpenAI" + sku = { + name = "S0" + } + properties = { + customSubDomainName = var.custom_subdomain # Required; must be globally unique + publicNetworkAccess = "Enabled" # Disable for production + disableLocalAuth = true # CRITICAL: Disable API keys, enforce AAD + networkAcls = { + defaultAction = "Allow" # Change to "Deny" with private endpoint + } + } + } + + tags = var.tags + + response_export_values = ["properties.endpoint"] +} +``` + +### Model Deployment + +```hcl +resource "azapi_resource" "gpt4o_deployment" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview" + name = "gpt-4o" + parent_id = azapi_resource.openai.id + + body = { + sku = { + name = "Standard" + capacity = 10 # Thousands of tokens per minute (10K TPM) + } + properties = { + model = { + format = "OpenAI" + name = "gpt-4o" + version = "2024-08-06" + } + raiPolicyName = "Microsoft.DefaultV2" + } + } +} + +resource "azapi_resource" "embedding_deployment" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview" + name = "text-embedding-3-small" + parent_id = azapi_resource.openai.id + + body = { + sku = { + name = "Standard" + capacity = 30 # 30K TPM for embeddings + } + properties = { + model = { + format = "OpenAI" + name = "text-embedding-3-small" + version = "1" + } + } + } + + depends_on = [azapi_resource.gpt4o_deployment] # Deploy sequentially to avoid conflicts +} +``` + +### RBAC Assignment + +```hcl +# Cognitive Services OpenAI User -- invoke models (chat, completions, embeddings) +resource "azapi_resource" "openai_user_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.openai.id}${var.managed_identity_principal_id}openai-user") + parent_id = azapi_resource.openai.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/5e0bd9bd-7b93-4f28-af87-19fc36ad61bd" # Cognitive Services OpenAI User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Cognitive Services OpenAI Contributor -- manage deployments + invoke +resource "azapi_resource" "openai_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.openai.id}${var.managed_identity_principal_id}openai-contributor") + parent_id = azapi_resource.openai.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/a001fd3d-188f-4b5d-821b-7da978bf7442" # Cognitive Services OpenAI Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Azure OpenAI account') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Custom subdomain name (must be globally unique)') +param customSubDomainName string + +@description('Tags to apply') +param tags object = {} + +resource openai 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = { + name: name + location: location + tags: tags + kind: 'OpenAI' + sku: { + name: 'S0' + } + properties: { + customSubDomainName: customSubDomainName + publicNetworkAccess: 'Enabled' + disableLocalAuth: true + networkAcls: { + defaultAction: 'Allow' + } + } +} + +resource gpt4oDeployment 'Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview' = { + parent: openai + name: 'gpt-4o' + sku: { + name: 'Standard' + capacity: 10 + } + properties: { + model: { + format: 'OpenAI' + name: 'gpt-4o' + version: '2024-08-06' + } + raiPolicyName: 'Microsoft.DefaultV2' + } +} + +resource embeddingDeployment 'Microsoft.CognitiveServices/accounts/deployments@2024-04-01-preview' = { + parent: openai + name: 'text-embedding-3-small' + sku: { + name: 'Standard' + capacity: 30 + } + properties: { + model: { + format: 'OpenAI' + name: 'text-embedding-3-small' + version: '1' + } + } + dependsOn: [gpt4oDeployment] +} + +output id string = openai.id +output name string = openai.name +output endpoint string = openai.properties.endpoint +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity') +param principalId string + +// Cognitive Services OpenAI User -- invoke models +resource openaiUserRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(openai.id, principalId, '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd') + scope: openai + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '5e0bd9bd-7b93-4f28-af87-19fc36ad61bd') // Cognitive Services OpenAI User + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Missing `customSubDomainName` | Account creation fails; required for token-based auth | Set a globally unique subdomain name | +| Using API keys instead of AAD | Secrets in config, key rotation burden | Set `disableLocalAuth = true`, assign Cognitive Services OpenAI User role | +| Deploying models in parallel | ARM conflicts when multiple deployments target the same account simultaneously | Use `depends_on` to serialize model deployments | +| Exceeding TPM quota | Requests throttled (HTTP 429) | Start with conservative TPM, request quota increases as needed | +| Wrong model region availability | Not all models are available in all regions | Check [model availability matrix](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) before selecting region | +| Content filter blocking legitimate requests | Requests rejected by default content filter | Review and customize content filtering policies if needed | +| Not using structured outputs | JSON parsing failures from unstructured responses | Use `response_format: { type: "json_object" }` or function calling for reliable structured output | + +## Production Backlog Items + +- [ ] Enable private endpoint and disable public network access +- [ ] Review and customize content filtering policies +- [ ] Configure diagnostic logging to Log Analytics workspace +- [ ] Set up monitoring alerts (token usage, throttling rate, error rate) +- [ ] Request production-level TPM quota increases +- [ ] Implement retry logic with exponential backoff in application code +- [ ] Configure customer managed keys for encryption at rest +- [ ] Set up model version pinning and upgrade schedule +- [ ] Review data, privacy, and abuse monitoring settings +- [ ] Consider provisioned throughput for predictable latency at scale diff --git a/azext_prototype/knowledge/services/azure-sql-database.md b/azext_prototype/knowledge/services/azure-sql-database.md new file mode 100644 index 0000000..150bc87 --- /dev/null +++ b/azext_prototype/knowledge/services/azure-sql-database.md @@ -0,0 +1,203 @@ +--- +service_namespace: Microsoft.Sql/servers/databases +display_name: Azure SQL Database +depends_on: + - Microsoft.Sql/servers +--- + +# Azure SQL Database + +> Fully managed relational database with built-in intelligence, serverless compute, and auto-pause for cost-effective POCs. + +## When to Use +- Applications requiring relational data with ACID transactions +- Workloads with complex queries, joins, stored procedures, or reporting needs +- Migration of existing SQL Server workloads to the cloud + +## POC Defaults +- **Compute tier**: Serverless (General Purpose) — auto-pauses after 60 minutes of inactivity +- **Max vCores**: 2 (sufficient for POC workloads) +- **Min vCores**: 0.5 (enables aggressive auto-pause savings) +- **Max storage**: 32 GB +- **SKU**: GP_S_Gen5 (General Purpose Serverless Gen5) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "sql_database" { + type = "Microsoft.Sql/servers/databases@2023-08-01-preview" + name = var.database_name + location = var.location + parent_id = azapi_resource.sql_server.id + + body = { + sku = { + name = "GP_S_Gen5" # General Purpose Serverless + tier = "GeneralPurpose" + family = "Gen5" + capacity = 2 # Max 2 vCores + } + properties = { + minCapacity = 0.5 + autoPauseDelay = 60 # Pause after 60 min idle + maxSizeBytes = 34359738368 # 32 GB + } + } + + tags = var.tags + response_export_values = ["*"] +} +``` + +### Data-Plane Access (T-SQL — NOT Terraform/Bicep) +```sql +-- CRITICAL: Azure SQL uses contained database users for data access. +-- You CANNOT grant database-level permissions via Terraform or Bicep. +-- Run this T-SQL as the AAD admin after deployment: + +CREATE USER [] FROM EXTERNAL PROVIDER; +ALTER ROLE db_datareader ADD MEMBER []; +ALTER ROLE db_datawriter ADD MEMBER []; + +-- The is the name of the User-Assigned Managed Identity resource. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param databaseName string +param location string = resourceGroup().location +param tags object = {} + +resource database 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { + parent: sqlServer + name: databaseName + location: location + sku: { + name: 'GP_S_Gen5' + tier: 'GeneralPurpose' + family: 'Gen5' + capacity: 2 + } + properties: { + minCapacity: json('0.5') + autoPauseDelay: 60 + maxSizeBytes: 34359738368 + } + tags: tags +} + +output databaseName string = database.name +output databaseId string = database.id +``` + +## Application Code + +### Python +```python +import pyodbc +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +token = credential.get_token("https://database.windows.net/.default") + +server = ".database.windows.net" +database = "" +conn_str = ( + f"Driver={{ODBC Driver 18 for SQL Server}};" + f"Server=tcp:{server},1433;" + f"Database={database};" + f"Encrypt=yes;" + f"TrustServerCertificate=no;" +) + +# pyodbc uses SQL_COPT_SS_ACCESS_TOKEN for token-based auth +token_bytes = token.token.encode("utf-16-le") +token_struct = bytes([len(token_bytes) & 0xFF, (len(token_bytes) >> 8) & 0xFF]) + token_bytes + +conn = pyodbc.connect(conn_str, attrs_before={1256: token_struct}) +cursor = conn.cursor() +cursor.execute("SELECT TOP 10 * FROM dbo.MyTable") +rows = cursor.fetchall() +conn.close() +``` + +### C# +```csharp +using Azure.Identity; +using Microsoft.Data.SqlClient; + +var credential = new DefaultAzureCredential(); +var connectionString = new SqlConnectionStringBuilder +{ + DataSource = "tcp:.database.windows.net,1433", + InitialCatalog = "", + Encrypt = true, + TrustServerCertificate = false +}.ConnectionString; + +await using var connection = new SqlConnection(connectionString); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://database.windows.net/.default" }) +); +connection.AccessToken = token.Token; +await connection.OpenAsync(); + +await using var command = new SqlCommand("SELECT TOP 10 * FROM dbo.MyTable", connection); +await using var reader = await command.ExecuteReaderAsync(); +while (await reader.ReadAsync()) +{ + Console.WriteLine(reader[0]); +} +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { Connection, Request } from "tedious"; + +const credential = new DefaultAzureCredential(); +const token = await credential.getToken("https://database.windows.net/.default"); + +const config = { + server: ".database.windows.net", + authentication: { + type: "azure-active-directory-access-token" as const, + options: { token: token.token }, + }, + options: { + database: "", + encrypt: true, + port: 1433, + trustServerCertificate: false, + }, +}; + +const connection = new Connection(config); +connection.on("connect", (err) => { + if (err) { console.error("Connection failed:", err); return; } + const request = new Request("SELECT TOP 10 * FROM dbo.MyTable", (err, rowCount) => { + if (err) console.error(err); + connection.close(); + }); + request.on("row", (columns) => columns.forEach((col) => console.log(col.value))); + connection.execSql(request); +}); +connection.connect(); +``` + +## Common Pitfalls +- **Trying to use Azure RBAC for data access**: Azure SQL does NOT use `Microsoft.Authorization/roleAssignments` for data-plane access. You MUST create contained database users via T-SQL. This cannot be done in Terraform or Bicep. +- **Forgetting the post-deploy T-SQL step**: Infrastructure deployment creates the database, but application identity access requires a separate T-SQL script run by the AAD admin. +- **Serverless auto-pause latency**: First connection after auto-pause takes 30-60 seconds. Applications need appropriate connection timeout settings. +- **pyodbc token encoding**: The access token must be encoded as UTF-16-LE with a 2-byte length prefix. Common source of auth failures in Python. +- **ODBC driver requirement**: Python and Node.js connectivity requires ODBC Driver 18. Container images must include this driver. + +## Production Backlog Items +- Geo-replication (active geo-replication or failover groups) for disaster recovery +- Long-term backup retention (LTR) beyond the default 7-day PITR +- Elastic pools for multi-tenant scenarios with variable workloads +- Connection pooling and retry logic for production resilience +- Database-level firewall rules scoped to specific IP ranges diff --git a/azext_prototype/knowledge/services/azure-sql.md b/azext_prototype/knowledge/services/azure-sql.md index 31cbd54..d271387 100644 --- a/azext_prototype/knowledge/services/azure-sql.md +++ b/azext_prototype/knowledge/services/azure-sql.md @@ -1,344 +1,132 @@ -# Azure SQL Database - -> Fully managed relational database engine with built-in intelligence, high availability, and serverless compute for cost-effective POCs. - -## When to Use -- Applications requiring relational data with ACID transactions -- Workloads with complex queries, joins, stored procedures, or reporting needs -- Migration of existing SQL Server applications to the cloud - -## POC Defaults -- **Compute tier**: Serverless (General Purpose) -- auto-pauses after 60 minutes of inactivity -- **Max vCores**: 2 (sufficient for POC workloads) -- **Min vCores**: 0.5 (enables aggressive auto-pause savings) -- **Max storage**: 32 GB -- **Authentication**: Azure AD-only (no SQL authentication) - -## Terraform Patterns - -### Basic Resource -```hcl -data "azurerm_client_config" "current" {} - -resource "azurerm_mssql_server" "this" { - name = var.sql_server_name - resource_group_name = azurerm_resource_group.this.name - location = azurerm_resource_group.this.location - version = "12.0" - minimum_tls_version = "1.2" - - azuread_administrator { - login_username = var.aad_admin_login - object_id = var.aad_admin_object_id - tenant_id = data.azurerm_client_config.current.tenant_id - azuread_authentication_only = true # CRITICAL: Disable SQL authentication entirely - } - - tags = var.tags -} - -resource "azurerm_mssql_database" "this" { - name = var.database_name - server_id = azurerm_mssql_server.this.id - - # Serverless configuration - sku_name = "GP_S_Gen5_2" # General Purpose Serverless, Gen5, max 2 vCores - min_capacity = 0.5 - auto_pause_delay_in_minutes = 60 # Pause after 60 min idle - - max_size_gb = 32 - - tags = var.tags -} - -# Allow Azure services to connect (for managed identity access) -resource "azurerm_mssql_firewall_rule" "allow_azure" { - name = "AllowAzureServices" - server_id = azurerm_mssql_server.this.id - start_ip_address = "0.0.0.0" - end_ip_address = "0.0.0.0" -} -``` - -### RBAC Assignment -```hcl -# CRITICAL: Azure SQL uses contained database users, NOT standard Azure RBAC for data access. -# You CANNOT grant database-level permissions via Terraform or Bicep. -# After deployment, run T-SQL to create contained users: -# -# CREATE USER [] FROM EXTERNAL PROVIDER; -# ALTER ROLE db_datareader ADD MEMBER []; -# ALTER ROLE db_datawriter ADD MEMBER []; -# -# The identity-name is the name of the User-Assigned Managed Identity resource. - -# For CONTROL PLANE operations only (not data access): -resource "azurerm_role_assignment" "sql_contributor" { - scope = azurerm_mssql_server.this.id - role_definition_name = "SQL Server Contributor" - principal_id = azurerm_user_assigned_identity.this.principal_id -} -``` - -### Private Endpoint -```hcl -resource "azurerm_private_endpoint" "sql" { - name = "${var.sql_server_name}-pe" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - subnet_id = azurerm_subnet.private_endpoints.id - - private_service_connection { - name = "${var.sql_server_name}-psc" - private_connection_resource_id = azurerm_mssql_server.this.id - is_manual_connection = false - subresource_names = ["sqlServer"] - } - - private_dns_zone_group { - name = "default" - private_dns_zone_ids = [azurerm_private_dns_zone.sql.id] - } -} - -resource "azurerm_private_dns_zone" "sql" { - name = "privatelink.database.windows.net" - resource_group_name = azurerm_resource_group.this.name -} - -resource "azurerm_private_dns_zone_virtual_network_link" "sql" { - name = "sql-dns-link" - resource_group_name = azurerm_resource_group.this.name - private_dns_zone_name = azurerm_private_dns_zone.sql.name - virtual_network_id = azurerm_virtual_network.this.id -} -``` - -## Bicep Patterns - -### Basic Resource -```bicep -param sqlServerName string -param databaseName string -param location string = resourceGroup().location -param aadAdminLogin string -param aadAdminObjectId string -param tags object = {} - -resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = { - name: sqlServerName - location: location - properties: { - minimalTlsVersion: '1.2' - administrators: { - administratorType: 'ActiveDirectory' - principalType: 'Group' // or 'User', 'Application' - login: aadAdminLogin - sid: aadAdminObjectId - tenantId: subscription().tenantId - azureADOnlyAuthentication: true // CRITICAL: Disable SQL authentication - } - } - tags: tags -} - -resource database 'Microsoft.Sql/servers/databases@2023-08-01-preview' = { - parent: sqlServer - name: databaseName - location: location - sku: { - name: 'GP_S_Gen5' // General Purpose Serverless - tier: 'GeneralPurpose' - family: 'Gen5' - capacity: 2 // Max 2 vCores - } - properties: { - minCapacity: json('0.5') // Min vCores (use json() for decimal) - autoPauseDelay: 60 // Pause after 60 min idle - maxSizeBytes: 34359738368 // 32 GB - } - tags: tags -} - -// Allow Azure services -resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = { - parent: sqlServer - name: 'AllowAzureServices' - properties: { - startIpAddress: '0.0.0.0' - endIpAddress: '0.0.0.0' - } -} - -output sqlServerFqdn string = sqlServer.properties.fullyQualifiedDomainName -output databaseName string = database.name -``` - -### RBAC Assignment -```bicep -// CRITICAL: Azure SQL data-plane access uses T-SQL contained users, NOT Azure RBAC. -// After deployment, execute the following T-SQL against the database: -// -// CREATE USER [] FROM EXTERNAL PROVIDER; -// ALTER ROLE db_datareader ADD MEMBER []; -// ALTER ROLE db_datawriter ADD MEMBER []; -// -// This must be run by the AAD admin configured on the server. -// There is no Bicep/ARM resource that can do this. - -// Control-plane contributor role only (does NOT grant data access): -param principalId string - -var sqlContributorRoleId = '6d8ee4ec-f05a-4a1d-8b00-a9b17e38b437' - -resource sqlContributorRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(sqlServer.id, principalId, sqlContributorRoleId) - scope: sqlServer - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', sqlContributorRoleId) - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python -```python -import pyodbc -from azure.identity import DefaultAzureCredential - -credential = DefaultAzureCredential() - -# Get access token for Azure SQL -token = credential.get_token("https://database.windows.net/.default") - -# Build connection string with access token -server = ".database.windows.net" -database = "" -conn_str = ( - f"Driver={{ODBC Driver 18 for SQL Server}};" - f"Server=tcp:{server},1433;" - f"Database={database};" - f"Encrypt=yes;" - f"TrustServerCertificate=no;" -) - -# pyodbc uses SQL_COPT_SS_ACCESS_TOKEN for token-based auth -token_bytes = token.token.encode("utf-16-le") -token_struct = bytes([len(token_bytes) & 0xFF, (len(token_bytes) >> 8) & 0xFF]) + token_bytes - -conn = pyodbc.connect(conn_str, attrs_before={1256: token_struct}) - -cursor = conn.cursor() -cursor.execute("SELECT TOP 10 * FROM dbo.MyTable") -rows = cursor.fetchall() -for row in rows: - print(row) - -conn.close() -``` - -### C# -```csharp -using Azure.Identity; -using Microsoft.Data.SqlClient; - -var credential = new DefaultAzureCredential(); - -var connectionString = new SqlConnectionStringBuilder -{ - DataSource = "tcp:.database.windows.net,1433", - InitialCatalog = "", - Encrypt = true, - TrustServerCertificate = false -}.ConnectionString; - -await using var connection = new SqlConnection(connectionString); - -// Use Azure AD token for authentication -var token = await credential.GetTokenAsync( - new Azure.Core.TokenRequestContext(new[] { "https://database.windows.net/.default" }) -); -connection.AccessToken = token.Token; - -await connection.OpenAsync(); - -await using var command = new SqlCommand("SELECT TOP 10 * FROM dbo.MyTable", connection); -await using var reader = await command.ExecuteReaderAsync(); - -while (await reader.ReadAsync()) -{ - Console.WriteLine(reader[0]); -} -``` - -### Node.js -```typescript -import { DefaultAzureCredential } from "@azure/identity"; -import { Connection, Request } from "tedious"; - -const credential = new DefaultAzureCredential(); - -const token = await credential.getToken("https://database.windows.net/.default"); - -const config = { - server: ".database.windows.net", - authentication: { - type: "azure-active-directory-access-token" as const, - options: { - token: token.token, - }, - }, - options: { - database: "", - encrypt: true, - port: 1433, - trustServerCertificate: false, - }, -}; - -const connection = new Connection(config); - -connection.on("connect", (err) => { - if (err) { - console.error("Connection failed:", err); - return; - } - - const request = new Request("SELECT TOP 10 * FROM dbo.MyTable", (err, rowCount) => { - if (err) console.error(err); - console.log(`${rowCount} rows returned`); - connection.close(); - }); - - request.on("row", (columns) => { - columns.forEach((column) => console.log(column.value)); - }); - - connection.execSql(request); -}); - -connection.connect(); -``` - -## Common Pitfalls -- **Trying to use Azure RBAC for data access**: Azure SQL does NOT use `Microsoft.Authorization/roleAssignments` for data-plane access. You MUST create contained database users via T-SQL (`CREATE USER [name] FROM EXTERNAL PROVIDER`). This cannot be done in Terraform or Bicep. -- **Leaving SQL authentication enabled**: Always set `azuread_authentication_only = true` on the server. Without this, password-based SQL logins remain available. -- **Forgetting the post-deploy T-SQL step**: Infrastructure deployment creates the server and database, but application identity access requires a separate T-SQL script run by the AAD admin. -- **Serverless auto-pause latency**: First connection after auto-pause takes 30-60 seconds to resume. Applications need appropriate connection timeout settings. -- **pyodbc token encoding**: The access token must be encoded as UTF-16-LE with a 2-byte length prefix. This is a common source of authentication failures in Python. -- **ODBC driver requirement**: Python and Node.js connectivity requires ODBC Driver 18 for SQL Server installed on the host. Container images must include this driver. -- **Firewall for Azure services**: The `0.0.0.0` to `0.0.0.0` firewall rule allows all Azure services, not just your own. Use private endpoints for tighter control. - -## Production Backlog Items -- Geo-replication (active geo-replication or failover groups) for disaster recovery -- Long-term backup retention (LTR) beyond the default 7-day PITR -- Advanced Threat Protection and vulnerability assessments -- Elastic pools for multi-tenant scenarios with variable workloads -- Transparent Data Encryption with customer-managed keys (CMK) -- Auditing to Log Analytics or Storage Account -- Private endpoint with DNS integration (remove public firewall rules) -- Connection pooling and retry logic for production resilience -- Database-level firewall rules scoped to specific IP ranges +--- +service_namespace: Microsoft.Sql/servers +display_name: Azure SQL Server +--- + +# Azure SQL Server + +> Logical server instance that hosts Azure SQL databases. Manages authentication, firewall rules, TLS, and server-level configuration. + +## When to Use +- Parent resource for all Azure SQL databases +- Centralized authentication via Microsoft Entra (Azure AD) +- Server-level firewall and network access control + +## POC Defaults +- **Authentication**: Azure AD-only (no SQL authentication) +- **TLS**: Minimum version 1.2 +- **Firewall**: Allow Azure services (0.0.0.0 rule) for managed identity access + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "sql_server" { + type = "Microsoft.Sql/servers@2023-08-01-preview" + name = var.sql_server_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + minimalTlsVersion = "1.2" + administrators = { + administratorType = "ActiveDirectory" + principalType = "Group" # or "User", "Application" + login = var.aad_admin_login + sid = var.aad_admin_object_id + tenantId = var.tenant_id + azureADOnlyAuthentication = true # CRITICAL: Disable SQL authentication entirely + } + } + } + + tags = var.tags + response_export_values = ["*"] +} + +# Allow Azure services to connect (for managed identity access) +resource "azapi_resource" "sql_firewall_allow_azure" { + type = "Microsoft.Sql/servers/firewallRules@2023-08-01-preview" + name = "AllowAzureServices" + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + startIpAddress = "0.0.0.0" + endIpAddress = "0.0.0.0" + } + } +} +``` + +### RBAC Assignment (Control Plane Only) +```hcl +# CRITICAL: This is a CONTROL PLANE role only — it does NOT grant data access. +# Data access uses T-SQL contained users (see Microsoft.Sql/servers/databases knowledge). +resource "azapi_resource" "sql_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${azapi_resource.sql_server.id}-${var.principal_id}-6d8ee4ec") + parent_id = azapi_resource.sql_server.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/6d8ee4ec-f05a-4a1d-8b00-a9b17e38b437" # SQL Server Contributor + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param sqlServerName string +param location string = resourceGroup().location +param aadAdminLogin string +param aadAdminObjectId string +param tags object = {} + +resource sqlServer 'Microsoft.Sql/servers@2023-08-01-preview' = { + name: sqlServerName + location: location + properties: { + minimalTlsVersion: '1.2' + administrators: { + administratorType: 'ActiveDirectory' + principalType: 'Group' + login: aadAdminLogin + sid: aadAdminObjectId + tenantId: subscription().tenantId + azureADOnlyAuthentication: true + } + } + tags: tags +} + +resource firewallRule 'Microsoft.Sql/servers/firewallRules@2023-08-01-preview' = { + parent: sqlServer + name: 'AllowAzureServices' + properties: { + startIpAddress: '0.0.0.0' + endIpAddress: '0.0.0.0' + } +} + +output sqlServerId string = sqlServer.id +output sqlServerName string = sqlServer.name +output sqlServerFqdn string = sqlServer.properties.fullyQualifiedDomainName +``` + +## Common Pitfalls +- **Leaving SQL authentication enabled**: Always set `azureADOnlyAuthentication = true`. Without this, password-based SQL logins remain available. +- **Firewall for Azure services**: The `0.0.0.0` to `0.0.0.0` rule allows ALL Azure services, not just your own. Use private endpoints for tighter control. +- **Confusing control-plane vs data-plane roles**: SQL Server Contributor is a control-plane role (manage server settings). Data access requires T-SQL contained users on the database. + +## Production Backlog Items +- Private endpoint with DNS integration (remove public firewall rules) +- Advanced Threat Protection and vulnerability assessments +- Auditing to Log Analytics or Storage Account +- Transparent Data Encryption with customer-managed keys (CMK) diff --git a/azext_prototype/knowledge/services/backup-vault-policy.md b/azext_prototype/knowledge/services/backup-vault-policy.md new file mode 100644 index 0000000..80e08e3 --- /dev/null +++ b/azext_prototype/knowledge/services/backup-vault-policy.md @@ -0,0 +1,178 @@ +--- +service_namespace: Microsoft.DataProtection/backupVaults/backupPolicies +display_name: Backup Vault Policy +depends_on: + - Microsoft.DataProtection/backupVaults +--- + +# Backup Vault Policy + +> Defines backup schedule and retention rules for resources protected by an Azure Backup vault (newer service supporting Blobs, Disks, PostgreSQL, AKS, and other modern workloads). + +## When to Use +- Backup Azure Managed Disks with configurable retention +- Backup Azure Blobs (operational or vaulted) +- Backup Azure Database for PostgreSQL servers +- Backup AKS clusters +- Different from Recovery Services vault policies — Backup vault uses the newer DataProtection API + +## POC Defaults +- **Frequency**: Daily +- **Retention**: 30 days default retention rule +- **Data store**: Operational store (for blobs/disks) or Vault store (for vaulted backups) +- **Time zone**: UTC + +## Terraform Patterns + +### Basic Resource +```hcl +# Disk backup policy +resource "azapi_resource" "backup_vault_policy" { + type = "Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01" + name = var.policy_name + parent_id = azapi_resource.backup_vault.id + + body = { + properties = { + datasourceTypes = ["Microsoft.Compute/disks"] + objectType = "BackupPolicy" + policyRules = [ + { + name = "BackupDaily" + objectType = "AzureBackupRule" + backupParameters = { + objectType = "AzureBackupParams" + backupType = "Incremental" + } + trigger = { + objectType = "ScheduleBasedTriggerContext" + schedule = { + repeatingTimeIntervals = ["R/2025-01-01T02:00:00+00:00/P1D"] + timeZone = "UTC" + } + taggingCriteria = [ + { + isDefault = true + tagInfo = { tagName = "Default" } + taggingPriority = 99 + } + ] + } + dataStore = { + objectType = "DataStoreInfoBase" + dataStoreType = "OperationalStore" + } + }, + { + name = "RetentionDefault" + objectType = "AzureRetentionRule" + isDefault = true + lifecycles = [ + { + deleteAfter = { + objectType = "AbsoluteDeleteOption" + duration = "P30D" + } + sourceDataStore = { + objectType = "DataStoreInfoBase" + dataStoreType = "OperationalStore" + } + } + ] + } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Backup Contributor role on the Backup vault allows policy management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param policyName string + +resource backupPolicy 'Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01' = { + parent: backupVault + name: policyName + properties: { + datasourceTypes: ['Microsoft.Compute/disks'] + objectType: 'BackupPolicy' + policyRules: [ + { + name: 'BackupDaily' + objectType: 'AzureBackupRule' + backupParameters: { + objectType: 'AzureBackupParams' + backupType: 'Incremental' + } + trigger: { + objectType: 'ScheduleBasedTriggerContext' + schedule: { + repeatingTimeIntervals: ['R/2025-01-01T02:00:00+00:00/P1D'] + timeZone: 'UTC' + } + taggingCriteria: [ + { + isDefault: true + tagInfo: { tagName: 'Default' } + taggingPriority: 99 + } + ] + } + dataStore: { + objectType: 'DataStoreInfoBase' + dataStoreType: 'OperationalStore' + } + } + { + name: 'RetentionDefault' + objectType: 'AzureRetentionRule' + isDefault: true + lifecycles: [ + { + deleteAfter: { + objectType: 'AbsoluteDeleteOption' + duration: 'P30D' + } + sourceDataStore: { + objectType: 'DataStoreInfoBase' + dataStoreType: 'OperationalStore' + } + } + ] + } + ] + } +} +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **Complex policy rule structure**: Backup vault policies use a deeply nested object model with `objectType` discriminators. Missing or wrong `objectType` values cause cryptic validation errors. +- **datasourceTypes must match**: The `datasourceTypes` array must match the workload type exactly (e.g., `Microsoft.Compute/disks`, `Microsoft.Storage/storageAccounts/blobServices`). +- **ISO 8601 repeating intervals**: Schedule uses `R/datetime/interval` format (e.g., `R/2025-01-01T02:00:00+00:00/P1D` for daily). This format differs from Recovery Services vault schedules. +- **Different from Recovery Services**: Backup vault (DataProtection) and Recovery Services vault (RecoveryServices) are different services with different APIs. Don't mix them. +- **Tagging criteria required**: Even for simple policies, the `taggingCriteria` with a default tag is mandatory. Omitting it fails validation. + +## Production Backlog Items +- Weekly and monthly retention rules with separate tags +- Vault store backup for long-term retention with cross-region +- Multiple data source support (blobs + disks in one vault) +- Backup instance monitoring and compliance reporting +- Cost optimization reviews for backup storage diff --git a/azext_prototype/knowledge/services/backup-vault.md b/azext_prototype/knowledge/services/backup-vault.md new file mode 100644 index 0000000..93871dd --- /dev/null +++ b/azext_prototype/knowledge/services/backup-vault.md @@ -0,0 +1,239 @@ +--- +service_namespace: Microsoft.DataProtection/backupVaults +display_name: Azure Backup Vault +--- + +# Azure Backup Vault +> Purpose-built vault for newer Azure Backup workloads including Azure Disks, Azure Blobs, Azure Database for PostgreSQL, and Azure Kubernetes Service, using Backup policies with immutability and soft delete support. + +## When to Use + +- Backing up Azure Managed Disks (snapshot-based) +- Backing up Azure Blob Storage (operational and vaulted backups) +- Backing up Azure Database for PostgreSQL Flexible Server +- Backing up AKS clusters +- When you need immutable vaults for ransomware protection +- NOT suitable for: VM backups, SQL Server in VMs, Azure Files, or SAP HANA (use Recovery Services vault instead) + +**Key distinction**: Backup Vault (`Microsoft.DataProtection/backupVaults`) supports newer workloads. Recovery Services vault (`Microsoft.RecoveryServices/vaults`) supports classic workloads (VMs, SQL, Files). Some workloads overlap; check current support matrix. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Storage setting | LocallyRedundant | GeoRedundant for production | +| Soft delete | Enabled (14 days) | Built-in, always enabled | +| Immutability | Disabled | Enable for production compliance | +| Cross-region restore | Disabled | Enable with GeoRedundant storage | +| Identity | System-assigned | Required for backup operations | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "backup_vault" { + type = "Microsoft.DataProtection/backupVaults@2024-04-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + storageSettings = [ + { + datastoreType = "VaultStore" + type = "LocallyRedundant" # GeoRedundant for production + } + ] + securitySettings = { + softDeleteSettings = { + state = "On" + retentionDurationInDays = 14 + } + } + } + } + + tags = var.tags +} +``` + +### Backup Policy for Managed Disks + +```hcl +resource "azapi_resource" "disk_backup_policy" { + type = "Microsoft.DataProtection/backupVaults/backupPolicies@2024-04-01" + name = var.policy_name + parent_id = azapi_resource.backup_vault.id + + body = { + properties = { + policyRules = [ + { + name = "BackupDaily" + objectType = "AzureBackupRule" + backupParameters = { + objectType = "AzureBackupParams" + backupType = "Incremental" + } + trigger = { + objectType = "ScheduleBasedTriggerContext" + schedule = { + repeatingTimeIntervals = ["R/2024-01-01T02:00:00+00:00/P1D"] + } + taggingCriteria = [ + { + isDefault = true + tagInfo = { + tagName = "Default" + } + taggingPriority = 99 + } + ] + } + dataStore = { + objectType = "DataStoreInfoBase" + dataStoreType = "OperationalStore" + } + }, + { + name = "RetentionDefault" + objectType = "AzureRetentionRule" + isDefault = true + lifecycles = [ + { + deleteAfter = { + objectType = "AbsoluteDeleteOption" + duration = "P7D" # 7-day retention for POC + } + sourceDataStore = { + objectType = "DataStoreInfoBase" + dataStoreType = "OperationalStore" + } + } + ] + } + ] + datasourceTypes = ["Microsoft.Compute/disks"] + objectType = "BackupPolicy" + } + } +} +``` + +### RBAC Assignment + +```hcl +# Grant Backup Vault identity Disk Snapshot Contributor on the disk resource group +resource "azapi_resource" "snapshot_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.disk_resource_group_id}${azapi_resource.backup_vault.identity[0].principal_id}disk-snapshot") + parent_id = var.disk_resource_group_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/7efff54f-a5b4-42b5-a1c5-5411624893ce" # Disk Snapshot Contributor + principalId = azapi_resource.backup_vault.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant Backup Vault identity Disk Backup Reader on the disk +resource "azapi_resource" "disk_backup_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.disk_id}${azapi_resource.backup_vault.identity[0].principal_id}disk-backup-reader") + parent_id = var.disk_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/3e5e47e6-65f7-47ef-90b5-e5dd4d455f24" # Disk Backup Reader + principalId = azapi_resource.backup_vault.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param tags object = {} + +resource backupVault 'Microsoft.DataProtection/backupVaults@2024-04-01' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + storageSettings: [ + { + datastoreType: 'VaultStore' + type: 'LocallyRedundant' + } + ] + securitySettings: { + softDeleteSettings: { + state: 'On' + retentionDurationInDays: 14 + } + } + } +} + +output id string = backupVault.id +output name string = backupVault.name +output principalId string = backupVault.identity.principalId +``` + +### RBAC Assignment + +```bicep +param diskResourceGroupId string +param principalId string + +// Disk Snapshot Contributor +resource snapshotContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(diskResourceGroupId, principalId, '7efff54f-a5b4-42b5-a1c5-5411624893ce') + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7efff54f-a5b4-42b5-a1c5-5411624893ce') + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Confusing Backup Vault with Recovery Services vault | Wrong vault type for the workload; deployment fails | Use Backup Vault for disks/blobs/PostgreSQL; Recovery Services for VMs/SQL/Files | +| Missing RBAC on source resources | Backup jobs fail with permission errors | Grant Disk Snapshot Contributor + Disk Backup Reader before configuring backup | +| LocallyRedundant in production | No cross-region protection against regional outage | Use GeoRedundant storage for production workloads | +| Not setting retention policy | Default retention may not meet compliance requirements | Explicitly configure retention duration in backup policy | +| Immutability lock misconfiguration | Cannot delete backups even if needed (locked state) | Start with unlocked immutability; lock only after validation | +| Snapshot resource group not specified | Snapshots created in source disk RG, cluttering it | Specify a dedicated snapshot resource group in backup instance | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Geo-redundant storage | P1 | Switch to GeoRedundant storage for cross-region resilience | +| Immutable vault | P1 | Enable vault immutability for ransomware protection | +| Cross-region restore | P2 | Enable cross-region restore for disaster recovery scenarios | +| Monitoring and alerts | P2 | Configure backup alerts via Azure Monitor for failed backup jobs | +| Multi-user authorization | P2 | Require Resource Guard approval for critical backup operations | +| Extended retention | P3 | Configure long-term retention policies for compliance (monthly/yearly) | +| Backup reports | P3 | Enable Backup Reports via Log Analytics for compliance auditing | +| Cost optimization | P3 | Review and right-size backup frequency and retention based on RPO requirements | diff --git a/azext_prototype/knowledge/services/bastion.md b/azext_prototype/knowledge/services/bastion.md new file mode 100644 index 0000000..bf0432a --- /dev/null +++ b/azext_prototype/knowledge/services/bastion.md @@ -0,0 +1,250 @@ +--- +service_namespace: Microsoft.Network/bastionHosts +display_name: Azure Bastion +--- + +# Azure Bastion +> Fully managed PaaS service providing secure RDP and SSH access to virtual machines over TLS, without exposing public IPs on VMs. + +## When to Use + +- **Secure VM management** -- access VMs via browser-based RDP/SSH without public IPs +- **Jump box replacement** -- eliminates need for self-managed jump boxes or VPN for VM access +- **Private AKS clusters** -- access API server of private Kubernetes clusters via Bastion host +- **DevOps agent access** -- SSH into self-hosted build agents in private VNets +- **Compliance requirements** -- audit trail for all management sessions (no direct RDP/SSH exposure) + +Azure Bastion is a **management-plane service** -- it provides secure access to compute resources but does not carry production application traffic. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | Developer SKU for single connection; Basic for small teams | +| Subnet name | AzureBastionSubnet | Must be exactly this name (Azure requirement) | +| Subnet size | /26 minimum | 64 addresses; /26 is the minimum for Bastion | +| Public IP | Standard SKU, Static | Required for Bastion | +| Scale units | 2 (Basic default) | Each unit supports ~20 concurrent sessions | +| Copy/paste | Enabled | Browser clipboard integration | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "bastion_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "AzureBastionSubnet" # Must be exactly this name + parent_id = var.virtual_network_id + + body = { + properties = { + addressPrefix = var.bastion_subnet_prefix # e.g., "10.0.10.0/26" + } + } +} + +resource "azapi_resource" "bastion_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "bastion" { + type = "Microsoft.Network/bastionHosts@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Basic" # "Standard" for tunneling, shareable links, Kerberos + } + properties = { + ipConfigurations = [ + { + name = "bastion-ip-config" + properties = { + publicIPAddress = { + id = azapi_resource.bastion_pip.id + } + subnet = { + id = azapi_resource.bastion_subnet.id + } + } + } + ] + } + } + + tags = var.tags +} +``` + +### Standard SKU with Native Client and Tunneling + +```hcl +resource "azapi_resource" "bastion_standard" { + type = "Microsoft.Network/bastionHosts@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + ipConfigurations = [ + { + name = "bastion-ip-config" + properties = { + publicIPAddress = { + id = azapi_resource.bastion_pip.id + } + subnet = { + id = azapi_resource.bastion_subnet.id + } + } + } + ] + enableTunneling = true # az network bastion tunnel + enableIpConnect = true # Connect by IP address + scaleUnits = 2 + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Reader role on the VM is required to connect via Bastion +resource "azapi_resource" "vm_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.vm_id}-${var.user_principal_id}-reader") + parent_id = var.vm_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7" # Reader + principalId = var.user_principal_id + principalType = "User" + } + } +} + +# Bastion itself does not require data-plane RBAC +# Users need Reader on the target VM + network connectivity +``` + +### Private Endpoint + +Azure Bastion does not support private endpoints -- it is a public-facing management service by design. The Bastion host uses a public IP to accept browser connections and then connects privately to VMs within the VNet. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Bastion host') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Virtual network ID') +param virtualNetworkId string + +@description('Bastion subnet prefix (min /26)') +param bastionSubnetPrefix string = '10.0.10.0/26' + +@description('Tags to apply') +param tags object = {} + +resource bastionSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + name: '${split(virtualNetworkId, '/')[8]}/AzureBastionSubnet' + properties: { + addressPrefix: bastionSubnetPrefix + } +} + +resource bastionPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource bastion 'Microsoft.Network/bastionHosts@2024-01-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Basic' + } + properties: { + ipConfigurations: [ + { + name: 'bastion-ip-config' + properties: { + publicIPAddress: { + id: bastionPip.id + } + subnet: { + id: bastionSubnet.id + } + } + } + ] + } +} + +output id string = bastion.id +output dnsName string = bastion.properties.dnsName +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Wrong subnet name | Deployment fails immediately | Subnet must be named exactly `AzureBastionSubnet` | +| Subnet too small | Bastion cannot deploy | Minimum /26 (64 addresses); /26 sufficient for most POCs | +| Using Basic/Dynamic public IP | Bastion requires Standard SKU | Use `Standard` SKU with `Static` allocation | +| Forgetting VM Reader role | Users see Bastion UI but cannot connect to VMs | Assign Reader role on target VMs to connecting users | +| Basic SKU limitations | No native client tunneling, no IP-based connect | Use Standard SKU if `az network bastion tunnel` is needed | +| Deployment time | Bastion takes 10-15 minutes to deploy | Plan for long provisioning in deployment pipelines | +| NSG on AzureBastionSubnet | Connectivity breaks if required rules are missing | Follow Azure docs for required NSG inbound/outbound rules | +| Cost surprise | Bastion incurs hourly charges even when idle | Basic SKU is ~$0.19/hour; Developer SKU is cheaper for single-user | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Standard SKU upgrade | P2 | Upgrade to Standard for native client tunneling and IP-based connect | +| Diagnostic logging | P2 | Enable Bastion session logs to Log Analytics for audit trail | +| NSG hardening | P1 | Apply recommended NSG rules to AzureBastionSubnet per Azure documentation | +| Scale units | P3 | Increase scale units for concurrent session capacity (Standard SKU) | +| Shareable links | P3 | Enable shareable links for time-limited VM access without portal (Standard SKU) | +| Session recording | P2 | Integrate session recording for compliance and security audit | +| Multi-VNet access | P3 | Configure VNet peering for Bastion to reach VMs in peered VNets | +| Kerberos auth | P3 | Enable Kerberos authentication for domain-joined VMs (Standard SKU) | diff --git a/azext_prototype/knowledge/services/batch-pool.md b/azext_prototype/knowledge/services/batch-pool.md new file mode 100644 index 0000000..a32fbcc --- /dev/null +++ b/azext_prototype/knowledge/services/batch-pool.md @@ -0,0 +1,171 @@ +--- +service_namespace: Microsoft.Batch/batchAccounts/pools +display_name: Batch Pool +depends_on: + - Microsoft.Batch/batchAccounts +--- + +# Batch Pool + +> A collection of compute nodes (VMs) within a Batch account that execute tasks. Pools define the VM size, OS, scaling rules, and networking for batch workloads. + +## When to Use +- Run parallel compute tasks across multiple VMs +- Configure auto-scaling pools that grow/shrink based on workload +- Define specific VM images and sizes for batch processing +- Support GPU workloads (rendering, ML training) with specialized VM SKUs +- Separate pool definitions for different workload types (CPU-intensive, memory-intensive) + +## POC Defaults +- **VM size**: Standard_D2s_v3 (general purpose, 2 vCPU, 8 GB RAM) +- **Target dedicated nodes**: 0 (scale up on demand) +- **Target low-priority nodes**: 2 (cost-effective for POC) +- **OS**: Ubuntu 22.04 LTS (via ImageReference) +- **Scaling**: Fixed for POC; auto-scale for production + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "batch_pool" { + type = "Microsoft.Batch/batchAccounts/pools@2024-07-01" + name = var.pool_name + parent_id = azapi_resource.batch_account.id + + body = { + properties = { + vmSize = "standard_d2s_v3" + deploymentConfiguration = { + virtualMachineConfiguration = { + imageReference = { + publisher = "canonical" + offer = "0001-com-ubuntu-server-jammy" + sku = "22_04-lts" + version = "latest" + } + nodeAgentSkuId = "batch.node.ubuntu 22.04" + } + } + scaleSettings = { + fixedScale = { + targetDedicatedNodes = 0 + targetLowPriorityNodes = 2 + resizeTimeout = "PT15M" + } + } + taskSlotsPerNode = 1 + } + } +} +``` + +### RBAC Assignment +```hcl +# Pool management inherits from the Batch Account RBAC. +# Batch Account Contributor role allows full pool management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param poolName string +param vmSize string = 'standard_d2s_v3' + +resource pool 'Microsoft.Batch/batchAccounts/pools@2024-07-01' = { + parent: batchAccount + name: poolName + properties: { + vmSize: vmSize + deploymentConfiguration: { + virtualMachineConfiguration: { + imageReference: { + publisher: 'canonical' + offer: '0001-com-ubuntu-server-jammy' + sku: '22_04-lts' + version: 'latest' + } + nodeAgentSkuId: 'batch.node.ubuntu 22.04' + } + } + scaleSettings: { + fixedScale: { + targetDedicatedNodes: 0 + targetLowPriorityNodes: 2 + resizeTimeout: 'PT15M' + } + } + } +} + +output poolId string = pool.id +output poolName string = pool.name +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.batch import BatchServiceClient +from azure.batch.models import PoolAddParameter, VirtualMachineConfiguration, ImageReference + +credential = DefaultAzureCredential() +batch_client = BatchServiceClient(credential, batch_url=f"https://{account_name}.{region}.batch.azure.com") + +# Submit a task to the pool +from azure.batch.models import TaskAddParameter +batch_client.task.add( + job_id=job_id, + task=TaskAddParameter( + id="task-1", + command_line="/bin/bash -c 'echo Hello Batch'" + ) +) +``` + +### C# +```csharp +using Azure.Identity; +using Microsoft.Azure.Batch; +using Microsoft.Azure.Batch.Auth; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://batch.core.windows.net/.default" })); + +using var batchClient = BatchClient.Open( + new BatchTokenCredentials($"https://{accountName}.{region}.batch.azure.com", () => + Task.FromResult(token.Token))); + +batchClient.JobOperations.AddTask(jobId, new CloudTask("task-1", "echo Hello Batch")); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { BatchServiceClient } from "@azure/batch"; + +const credential = new DefaultAzureCredential(); +const batchClient = new BatchServiceClient(credential, + `https://${accountName}.${region}.batch.azure.com`); + +await batchClient.task.add(jobId, { + id: "task-1", + commandLine: "/bin/bash -c 'echo Hello Batch'", +}); +``` + +## Common Pitfalls +- **Node agent SKU must match image**: The `nodeAgentSkuId` must correspond to the OS image. Mismatches cause pool creation to succeed but nodes fail to start. +- **Resize timeout**: If nodes can't be allocated within the resize timeout, the pool enters a resize error state. Low-priority nodes are especially prone to this. +- **Low-priority preemption**: Low-priority nodes can be preempted at any time. Tasks must be idempotent or use retry logic. +- **VNet integration complexity**: Pools in VNets require specific NSG rules allowing Batch node management traffic (ports 29876, 29877, 443). +- **Pool deletion is async**: Deleting a pool with running nodes can take several minutes. Terraform may timeout waiting for deletion. + +## Production Backlog Items +- Auto-scale formulas based on pending task count +- VNet integration for network-isolated workloads +- Container-based task execution (Docker images) +- Start task for node initialization (install dependencies) +- Application packages for versioned task binaries diff --git a/azext_prototype/knowledge/services/batch.md b/azext_prototype/knowledge/services/batch.md new file mode 100644 index 0000000..089e6f2 --- /dev/null +++ b/azext_prototype/knowledge/services/batch.md @@ -0,0 +1,340 @@ +--- +service_namespace: Microsoft.Batch/batchAccounts +display_name: Azure Batch +--- + +# Azure Batch +> Managed service for running large-scale parallel and high-performance computing (HPC) workloads with automatic VM provisioning and job scheduling. + +## When to Use + +- **Parallel processing** -- large-scale batch jobs that can be split into independent tasks (rendering, simulations, data processing) +- **HPC workloads** -- computational fluid dynamics, finite element analysis, molecular dynamics +- **Media encoding** -- video transcoding and image processing at scale +- **Data transformation** -- ETL jobs that process millions of files in parallel +- **Machine learning training** -- distributed hyperparameter tuning across many VMs + +Choose Batch over AKS when the workload is embarrassingly parallel with independent tasks, does not need long-running infrastructure, and benefits from automatic VM scaling to zero. Choose AKS for always-on microservices or workloads that need Kubernetes orchestration. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Account allocation mode | Batch service | User subscription mode needed for VNet injection | +| Pool VM size | Standard_D2s_v5 | 2 vCPU, 8 GiB; sufficient for POC tasks | +| Pool allocation | Auto-scale | Scale to zero when idle to minimize cost | +| Target dedicated nodes | 0-2 | Low-priority/spot for cost savings | +| OS | Ubuntu 22.04 LTS | Linux preferred for most batch workloads | +| Managed identity | User-assigned | For accessing storage and other Azure resources | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "batch_account" { + type = "Microsoft.Batch/batchAccounts@2024-02-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + properties = { + poolAllocationMode = "BatchService" + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + autoStorage = { + storageAccountId = var.storage_account_id + authenticationMode = "BatchAccountManagedIdentity" + nodeIdentityReference = { + resourceId = var.managed_identity_id + } + } + allowedAuthenticationModes = [ + "AAD" # Disable shared key; use Azure AD only + ] + } + } + + tags = var.tags + + response_export_values = ["properties.accountEndpoint"] +} +``` + +### Pool + +```hcl +resource "azapi_resource" "batch_pool" { + type = "Microsoft.Batch/batchAccounts/pools@2024-02-01" + name = var.pool_name + parent_id = azapi_resource.batch_account.id + + body = { + properties = { + vmSize = "Standard_D2s_v5" + deploymentConfiguration = { + virtualMachineConfiguration = { + imageReference = { + publisher = "canonical" + offer = "0001-com-ubuntu-server-jammy" + sku = "22_04-lts" + version = "latest" + } + nodeAgentSkuId = "batch.node.ubuntu 22.04" + } + } + scaleSettings = { + autoScale = { + formula = "$TargetDedicatedNodes = max(0, min($PendingTasks.GetSample(TimeInterval_Minute * 5), 4));" + evaluationInterval = "PT5M" + } + } + taskSlotsPerNode = 2 + identity = { + type = "UserAssigned" + userAssignedIdentities = [ + { + resourceId = var.managed_identity_id + } + ] + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# Batch Contributor -- allows submitting and managing jobs +resource "azapi_resource" "batch_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.batch_account.id}${var.managed_identity_principal_id}batch-contributor") + parent_id = azapi_resource.batch_account.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant batch pool identity access to storage for input/output +resource "azapi_resource" "storage_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}${var.managed_identity_principal_id}storage-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "batch_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.batch_account.id + groupIds = ["batchAccount"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "batch_pe_dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.batch_private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink..batch.azure.com` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Batch account') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Storage account ID for auto-storage') +param storageAccountId string + +@description('Managed identity resource ID') +param managedIdentityId string + +@description('Tags to apply') +param tags object = {} + +resource batchAccount 'Microsoft.Batch/batchAccounts@2024-02-01' = { + name: name + location: location + tags: tags + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + properties: { + poolAllocationMode: 'BatchService' + publicNetworkAccess: 'Disabled' + autoStorage: { + storageAccountId: storageAccountId + authenticationMode: 'BatchAccountManagedIdentity' + nodeIdentityReference: { + resourceId: managedIdentityId + } + } + allowedAuthenticationModes: [ + 'AAD' + ] + } +} + +output id string = batchAccount.id +output name string = batchAccount.name +output accountEndpoint string = batchAccount.properties.accountEndpoint +``` + +### Pool + +```bicep +@description('Pool name') +param poolName string + +@description('VM size for pool nodes') +param vmSize string = 'Standard_D2s_v5' + +@description('Managed identity resource ID for pool nodes') +param managedIdentityId string + +resource pool 'Microsoft.Batch/batchAccounts/pools@2024-02-01' = { + parent: batchAccount + name: poolName + properties: { + vmSize: vmSize + deploymentConfiguration: { + virtualMachineConfiguration: { + imageReference: { + publisher: 'canonical' + offer: '0001-com-ubuntu-server-jammy' + sku: '22_04-lts' + version: 'latest' + } + nodeAgentSkuId: 'batch.node.ubuntu 22.04' + } + } + scaleSettings: { + autoScale: { + formula: '$TargetDedicatedNodes = max(0, min($PendingTasks.GetSample(TimeInterval_Minute * 5), 4));' + evaluationInterval: 'PT5M' + } + } + taskSlotsPerNode: 2 + identity: { + type: 'UserAssigned' + userAssignedIdentities: [ + { + resourceId: managedIdentityId + } + ] + } + } +} +``` + +### RBAC Assignment + +```bicep +@description('Principal ID for the managed identity') +param principalId string + +resource batchContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(batchAccount.id, principalId, 'contributor') + scope: batchAccount + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c') // Contributor + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Auto-storage not configured | Tasks cannot stage input/output files | Always configure `autoStorage` with a storage account | +| Shared key auth left enabled | Security risk; keys can be leaked | Set `allowedAuthenticationModes` to `["AAD"]` only | +| Pool auto-scale formula errors | Pool stuck at 0 nodes or over-provisioned | Test formulas with evaluation endpoint before deploying | +| Node agent SKU mismatch | Pool creation fails silently | Match `nodeAgentSkuId` exactly to the image publisher/offer/sku | +| Missing start task | Nodes lack required software/config | Use start tasks for package installs and environment setup | +| Over-provisioning dedicated nodes | Unnecessary costs for POC | Use low-priority/spot nodes and auto-scale to zero | +| Forgetting task retry policy | Transient failures cause job failure | Set `maxTaskRetryCount` on job/task for fault tolerance | +| User subscription mode complexity | Requires additional VNet and quota config | Use Batch service allocation mode for POC simplicity | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| VNet integration | P1 | Switch to user subscription mode and deploy pools into VNet subnets | +| Private endpoint | P1 | Add private endpoint for Batch account management plane | +| Low-priority/spot nodes | P2 | Use spot VMs for cost savings on fault-tolerant workloads | +| Application packages | P2 | Package and version application binaries for deployment to nodes | +| Job scheduling | P3 | Configure job schedules for recurring batch processing | +| Monitoring and alerts | P2 | Set up alerts for pool resize failures, task failures, and quota usage | +| Customer-managed keys | P3 | Enable CMK encryption for data at rest | +| Container support | P3 | Run tasks in Docker containers for dependency isolation | +| Multi-region pools | P3 | Deploy pools across regions for disaster recovery | +| Certificate management | P3 | Configure certificates for tasks that need TLS client auth | diff --git a/azext_prototype/knowledge/services/bot-service-channel.md b/azext_prototype/knowledge/services/bot-service-channel.md new file mode 100644 index 0000000..b64178f --- /dev/null +++ b/azext_prototype/knowledge/services/bot-service-channel.md @@ -0,0 +1,181 @@ +--- +service_namespace: Microsoft.BotService/botServices/channels +display_name: Bot Service Channel +depends_on: + - Microsoft.BotService/botServices +--- + +# Bot Service Channel + +> Connects an Azure Bot to external messaging platforms (Microsoft Teams, Slack, Web Chat, Direct Line, etc.) for multi-channel bot experiences. + +## When to Use +- Enable Microsoft Teams integration for enterprise bots +- Add Web Chat channel for website-embedded chat widgets +- Configure Direct Line channel for custom client applications +- Connect to Slack, Facebook Messenger, or other third-party platforms +- Every bot needs at least one channel to be reachable by users + +## POC Defaults +- **Web Chat**: Enabled by default on bot creation +- **Direct Line**: Enabled for custom client apps and testing +- **Microsoft Teams**: Most common enterprise channel +- **Channel name convention**: `MsTeamsChannel`, `DirectLineChannel`, `WebChatChannel` + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "teams_channel" { + type = "Microsoft.BotService/botServices/channels@2022-09-15" + name = "MsTeamsChannel" + parent_id = azapi_resource.bot_service.id + location = "global" + + body = { + properties = { + channelName = "MsTeamsChannel" + properties = { + isEnabled = true + enableCalling = false + } + } + } +} + +resource "azapi_resource" "directline_channel" { + type = "Microsoft.BotService/botServices/channels@2022-09-15" + name = "DirectLineChannel" + parent_id = azapi_resource.bot_service.id + location = "global" + + body = { + properties = { + channelName = "DirectLineChannel" + properties = { + sites = [ + { + siteName = "default" + isEnabled = true + isV1Enabled = false + isV3Enabled = true + } + ] + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Channel management inherits from the Bot Service RBAC. +# No separate RBAC role exists for individual channels. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource teamsChannel 'Microsoft.BotService/botServices/channels@2022-09-15' = { + parent: botService + name: 'MsTeamsChannel' + location: 'global' + properties: { + channelName: 'MsTeamsChannel' + properties: { + isEnabled: true + enableCalling: false + } + } +} + +resource directLineChannel 'Microsoft.BotService/botServices/channels@2022-09-15' = { + parent: botService + name: 'DirectLineChannel' + location: 'global' + properties: { + channelName: 'DirectLineChannel' + properties: { + sites: [ + { + siteName: 'default' + isEnabled: true + isV1Enabled: false + isV3Enabled: true + } + ] + } + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from botbuilder.core import TurnContext +from botbuilder.schema import Activity + +# Channel-specific logic in the bot handler +class MyBot: + async def on_message_activity(self, turn_context: TurnContext): + channel = turn_context.activity.channel_id # "msteams", "directline", "webchat" + if channel == "msteams": + # Teams-specific adaptive card response + await turn_context.send_activity(Activity(type="message", text="Hello from Teams!")) + else: + await turn_context.send_activity("Hello from Bot!") +``` + +### C# +```csharp +using Microsoft.Bot.Builder; +using Microsoft.Bot.Schema; + +public class MyBot : ActivityHandler +{ + protected override async Task OnMessageActivityAsync(ITurnContext turnContext, CancellationToken ct) + { + var channel = turnContext.Activity.ChannelId; // "msteams", "directline", "webchat" + if (channel == "msteams") + await turnContext.SendActivityAsync(MessageFactory.Text("Hello from Teams!"), ct); + else + await turnContext.SendActivityAsync(MessageFactory.Text("Hello from Bot!"), ct); + } +} +``` + +### Node.js +```typescript +import { ActivityHandler, TurnContext } from "botbuilder"; + +class MyBot extends ActivityHandler { + constructor() { + super(); + this.onMessage(async (context: TurnContext) => { + const channel = context.activity.channelId; // "msteams", "directline", "webchat" + if (channel === "msteams") { + await context.sendActivity("Hello from Teams!"); + } else { + await context.sendActivity("Hello from Bot!"); + } + }); + } +} +``` + +## Common Pitfalls +- **Channel name is the resource name**: The resource name must exactly match the channel identifier (e.g., `MsTeamsChannel`, `DirectLineChannel`). Arbitrary names fail. +- **Location must be 'global'**: Bot Service channels always use `global` as the location, regardless of the bot's region. +- **Teams app registration**: Enabling Teams channel is just the Azure side — you also need a Teams app manifest and deployment to the Teams app catalog. +- **Direct Line secrets rotation**: Direct Line channel secrets should be rotated regularly. The initial secrets are retrievable via the API. +- **Web Chat is auto-created**: The Web Chat channel is created automatically with the bot. Recreating it may cause conflicts. + +## Production Backlog Items +- Teams app manifest and deployment to organization app catalog +- Direct Line secret rotation on a schedule +- Enhanced authentication for Direct Line (trusted origins) +- Channel-specific adaptive card templates +- Bot analytics and conversation telemetry per channel diff --git a/azext_prototype/knowledge/services/bot-service.md b/azext_prototype/knowledge/services/bot-service.md new file mode 100644 index 0000000..e427e87 --- /dev/null +++ b/azext_prototype/knowledge/services/bot-service.md @@ -0,0 +1,213 @@ +--- +service_namespace: Microsoft.BotService/botServices +display_name: Azure Bot Service +--- + +# Azure Bot Service +> Managed platform for building, deploying, and managing intelligent bots that interact with users across channels like Teams, Web Chat, Slack, and more. + +## When to Use + +- **Conversational AI** -- chatbots powered by Azure OpenAI, Language Understanding, or custom NLP models +- **Microsoft Teams bots** -- internal enterprise bots for help desk, HR, IT automation +- **Multi-channel messaging** -- single bot deployed across Teams, Web Chat, Slack, Facebook, SMS +- **Customer support** -- automated FAQ, ticket routing, and live agent handoff +- **Virtual assistants** -- task-oriented bots for scheduling, ordering, or information retrieval + +Choose Bot Service over a standalone web API when you need built-in channel connectors, conversation state management, and the Bot Framework SDK. Choose a plain API if the interaction is request/response without conversational context. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | F0 (Free) | 10K messages/month; sufficient for POC | +| Kind | azurebot | Multi-channel registration (not legacy "sdk") | +| Messaging endpoint | App Service or Container Apps URL | Bot logic runs on separate compute | +| Authentication | User-assigned managed identity | For Azure resource access from bot code | +| App type | SingleTenant | Multi-tenant if external users need access | +| Channels | Web Chat, Teams | Enable others as needed | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "bot" { + type = "Microsoft.BotService/botServices@2022-09-15" + name = var.name + location = "global" # Bot registrations are global + parent_id = var.resource_group_id + + body = { + kind = "azurebot" + sku = { + name = "F0" # Free tier for POC + } + properties = { + displayName = var.display_name + endpoint = var.messaging_endpoint # https://.azurewebsites.net/api/messages + msaAppId = var.app_id # Azure AD app registration + msaAppType = "SingleTenant" + msaAppTenantId = var.tenant_id + disableLocalAuth = true # Disable legacy auth + isStreamingSupported = false + schemaTransformationVersion = "1.3" + } + } + + tags = var.tags +} +``` + +### Channel Configuration (Teams) + +```hcl +resource "azapi_resource" "teams_channel" { + type = "Microsoft.BotService/botServices/channels@2022-09-15" + name = "MsTeamsChannel" + parent_id = azapi_resource.bot.id + + body = { + properties = { + channelName = "MsTeamsChannel" + properties = { + isEnabled = true + } + } + } +} +``` + +### Channel Configuration (Web Chat) + +```hcl +resource "azapi_resource" "webchat_channel" { + type = "Microsoft.BotService/botServices/channels@2022-09-15" + name = "WebChatChannel" + parent_id = azapi_resource.bot.id + + body = { + properties = { + channelName = "WebChatChannel" + properties = {} + } + } +} +``` + +### RBAC Assignment + +```hcl +# Bot Service does not use Azure RBAC for data-plane access. +# The bot authenticates to Azure resources using the managed identity +# of its hosting compute (App Service or Container Apps). + +# Grant the hosting app's identity access to Azure OpenAI for chat completions +resource "azapi_resource" "openai_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.openai_account_id}${var.managed_identity_principal_id}cognitive-services-user") + parent_id = var.openai_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/a97b65f3-24c7-4388-baec-2e87135dc908" # Cognitive Services User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Bot Service registrations are global resources and do not support private endpoints. The bot logic runs on App Service, Container Apps, or Azure Functions, which have their own private endpoint configurations. Secure the hosting compute instead. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the bot registration') +param name string + +@description('Display name for the bot') +param displayName string + +@description('Messaging endpoint URL') +param messagingEndpoint string + +@description('Azure AD app registration ID') +param msaAppId string + +@description('Azure AD tenant ID') +param msaAppTenantId string + +@description('Tags to apply') +param tags object = {} + +resource bot 'Microsoft.BotService/botServices@2022-09-15' = { + name: name + location: 'global' + tags: tags + kind: 'azurebot' + sku: { + name: 'F0' + } + properties: { + displayName: displayName + endpoint: messagingEndpoint + msaAppId: msaAppId + msaAppType: 'SingleTenant' + msaAppTenantId: msaAppTenantId + disableLocalAuth: true + isStreamingSupported: false + schemaTransformationVersion: '1.3' + } +} + +resource teamsChannel 'Microsoft.BotService/botServices/channels@2022-09-15' = { + parent: bot + name: 'MsTeamsChannel' + properties: { + channelName: 'MsTeamsChannel' + properties: { + isEnabled: true + } + } +} + +output id string = bot.id +output name string = bot.name +``` + +### RBAC Assignment + +Bot Service uses Azure AD app registrations for authentication, not ARM RBAC. Grant roles to the hosting compute's managed identity for accessing backend Azure resources. + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Using legacy "sdk" kind | Creates deprecated v3 bot registration | Always use `kind: "azurebot"` for new bots | +| Wrong messaging endpoint | Bot unreachable; channels show errors | Endpoint must be HTTPS and end with `/api/messages` | +| Multi-tenant when single-tenant needed | Authentication failures for internal bots | Use `SingleTenant` for enterprise-only bots | +| Missing Azure AD app registration | Bot cannot authenticate to channels | Create an Azure AD app registration before the bot resource | +| Not configuring CORS on hosting app | Web Chat embed fails in browsers | Add the embedding domain to CORS allowed origins | +| Forgetting to enable Teams channel | Bot not visible in Teams | Explicitly add `MsTeamsChannel` resource | +| F0 tier message limits | Bot stops responding after 10K messages/month | Monitor usage; upgrade to S1 for production | +| Direct Line secret exposure | Unauthorized access to bot | Use Direct Line tokens (short-lived) instead of secrets in client code | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Upgrade to S1 SKU | P1 | Remove message limits for production traffic | +| App Insights integration | P2 | Enable bot telemetry with Application Insights for conversation analytics | +| Custom domain | P3 | Configure custom domain on hosting app for branded bot endpoints | +| Authentication (OAuth) | P2 | Add user authentication via OAuth connections for accessing user-scoped data | +| Proactive messaging | P3 | Implement proactive message support for notifications and alerts | +| Adaptive Cards | P3 | Build rich interactive card UIs for Teams and Web Chat | +| State management | P2 | Configure Cosmos DB or Blob Storage for durable conversation state | +| Rate limiting | P2 | Implement rate limiting to protect backend services from bot traffic spikes | +| Multi-language support | P3 | Add Translator integration for multi-language bot interactions | +| CI/CD pipeline | P2 | Automate bot deployment with staging slots and A/B testing | diff --git a/azext_prototype/knowledge/services/cdn-afd-endpoint-route.md b/azext_prototype/knowledge/services/cdn-afd-endpoint-route.md new file mode 100644 index 0000000..9a33eac --- /dev/null +++ b/azext_prototype/knowledge/services/cdn-afd-endpoint-route.md @@ -0,0 +1,96 @@ +--- +service_namespace: Microsoft.Cdn/profiles/afdEndpoints/routes +display_name: Front Door / CDN Route +depends_on: + - Microsoft.Cdn/profiles/afdEndpoints + - Microsoft.Cdn/profiles/originGroups +--- + +# Front Door / CDN Route + +> Maps incoming requests on an endpoint to an origin group based on path patterns. Controls caching, protocol, and forwarding behavior. + +## When to Use +- Every endpoint needs at least one route to forward traffic to origins +- Use multiple routes for different path patterns (e.g., `/api/*` vs `/static/*`) +- Configure caching rules per route + +## POC Defaults +- **Patterns to match**: `/*` (catch-all) +- **Forwarding protocol**: HTTPS only +- **Caching**: Disabled for API routes; enabled for static content + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "afd_route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = var.route_name + parent_id = azapi_resource.afd_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.origin_group.id + } + patternsToMatch = ["/*"] + forwardingProtocol = "HttpsOnly" + httpsRedirect = "Enabled" + linkToDefaultDomain = "Enabled" + } + } +} +``` + +### RBAC Assignment +```hcl +# Route management inherits from the parent CDN profile RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param routeName string +param originGroupId string + +resource route 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: afdEndpoint + name: routeName + properties: { + originGroup: { id: originGroupId } + patternsToMatch: ['/*'] + forwardingProtocol: 'HttpsOnly' + httpsRedirect: 'Enabled' + linkToDefaultDomain: 'Enabled' + } +} +``` + +## Application Code + +### Python +```python +# Routes are infrastructure — transparent to application code. +``` + +### C# +```csharp +// Routes are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Routes are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Route ordering matters**: More specific patterns should be evaluated before catch-all patterns. +- **Origin group required**: A route without an origin group has no backend to forward to. +- **HTTPS redirect**: Always enable `httpsRedirect` to ensure HTTP requests are upgraded. + +## Production Backlog Items +- Path-based routing for microservice backends +- Caching rules per route for static vs dynamic content +- Custom rule sets for header manipulation and URL rewrite diff --git a/azext_prototype/knowledge/services/cdn-afd-endpoint.md b/azext_prototype/knowledge/services/cdn-afd-endpoint.md new file mode 100644 index 0000000..90675de --- /dev/null +++ b/azext_prototype/knowledge/services/cdn-afd-endpoint.md @@ -0,0 +1,92 @@ +--- +service_namespace: Microsoft.Cdn/profiles/afdEndpoints +display_name: Front Door / CDN Endpoint +depends_on: + - Microsoft.Cdn/profiles +--- + +# Front Door / CDN Endpoint + +> An endpoint within an Azure Front Door or CDN profile that receives traffic on a custom or default domain. + +## When to Use +- Every Front Door profile needs at least one endpoint to receive traffic +- Endpoints define the public-facing FQDN for the application +- Multiple endpoints per profile for different applications or environments + +## POC Defaults +- **Enabled**: true +- **Domain**: Default Azure-provided FQDN (custom domain for production) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "afd_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.endpoint_name + location = "global" + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + enabledState = "Enabled" + } + } + + tags = var.tags + response_export_values = ["properties.hostName"] +} +``` + +### RBAC Assignment +```hcl +# Endpoint management inherits from the parent CDN profile RBAC. +# CDN Endpoint Contributor: 426e0c7f-0c7e-4658-b36f-ff54d6c29b45 +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param endpointName string + +resource endpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: cdnProfile + name: endpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } +} + +output hostName string = endpoint.properties.hostName +``` + +## Application Code + +### Python +```python +# CDN endpoints are infrastructure — applications are served through the endpoint URL. +# Configure the application's base URL to use the endpoint hostname. +``` + +### C# +```csharp +// CDN endpoints are infrastructure — configure base URL in appsettings.json. +``` + +### Node.js +```typescript +// CDN endpoints are infrastructure — configure base URL in environment variables. +``` + +## Common Pitfalls +- **Location must be "global"**: All Front Door / CDN endpoint resources are global. +- **Endpoint name becomes DNS**: The endpoint name is part of the default FQDN (e.g., `myendpoint.z01.azurefd.net`). +- **Routes required**: An endpoint without routes receives no traffic. Create routes to connect origins. + +## Production Backlog Items +- Custom domain with managed TLS certificate +- WAF policy association for application protection +- Multiple endpoints for multi-application profiles diff --git a/azext_prototype/knowledge/services/cdn-origin-group.md b/azext_prototype/knowledge/services/cdn-origin-group.md new file mode 100644 index 0000000..1f4c7f1 --- /dev/null +++ b/azext_prototype/knowledge/services/cdn-origin-group.md @@ -0,0 +1,105 @@ +--- +service_namespace: Microsoft.Cdn/profiles/originGroups +display_name: Front Door / CDN Origin Group +depends_on: + - Microsoft.Cdn/profiles +--- + +# Front Door / CDN Origin Group + +> A logical group of backend origins that Front Door load-balances across. Defines health probes and load balancing settings. + +## When to Use +- Group multiple origins for load balancing and failover +- Configure health probes to detect unhealthy origins +- One origin group per backend tier (e.g., API backends, static content) + +## POC Defaults +- **Health probe**: Enabled, HTTPS, path `/health`, interval 30s +- **Load balancing**: Round robin with 50ms latency sensitivity + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = var.origin_group_name + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/health" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Origin group management inherits from the parent CDN profile RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param originGroupName string + +resource originGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: cdnProfile + name: originGroupName + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/health' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + } +} + +output originGroupId string = originGroup.id +``` + +## Application Code + +### Python +```python +# Origin groups are infrastructure — transparent to application code. +# Ensure the application exposes a /health endpoint for health probes. +``` + +### C# +```csharp +// Ensure the application exposes a /health endpoint for health probes. +``` + +### Node.js +```typescript +// Ensure the application exposes a /health endpoint for health probes. +``` + +## Common Pitfalls +- **Health probe endpoint must exist**: If the probe path returns 4xx/5xx, the origin is marked unhealthy and receives no traffic. +- **Latency sensitivity**: The `additionalLatencyInMilliseconds` setting controls how much latency difference is acceptable before routing to a different origin. + +## Production Backlog Items +- Multi-region origin groups for geo-redundancy +- Weighted load balancing for gradual traffic migration +- Private Link origin connections for secure backend access diff --git a/azext_prototype/knowledge/services/cdn-origin.md b/azext_prototype/knowledge/services/cdn-origin.md new file mode 100644 index 0000000..80380b6 --- /dev/null +++ b/azext_prototype/knowledge/services/cdn-origin.md @@ -0,0 +1,99 @@ +--- +service_namespace: Microsoft.Cdn/profiles/originGroups/origins +display_name: Front Door / CDN Origin +depends_on: + - Microsoft.Cdn/profiles/originGroups +--- + +# Front Door / CDN Origin + +> A backend server or Azure service that serves content. Origins are grouped into origin groups for load balancing. + +## When to Use +- Point to Azure services (App Service, Container Apps, Storage) or custom hostnames +- Each origin group needs at least one origin +- Multiple origins in a group enable failover and load balancing + +## POC Defaults +- **HTTP port**: 80 +- **HTTPS port**: 443 +- **Priority**: 1 (all origins equal in POC) +- **Weight**: 1000 (equal weight) +- **Private Link**: Not enabled for POC + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "origin" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = var.origin_name + parent_id = azapi_resource.origin_group.id + + body = { + properties = { + hostName = var.origin_hostname # e.g., myapp.azurewebsites.net + httpPort = 80 + httpsPort = 443 + originHostHeader = var.origin_hostname + priority = 1 + weight = 1000 + enabledState = "Enabled" + } + } +} +``` + +### RBAC Assignment +```hcl +# Origin management inherits from the parent CDN profile RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param originName string +param originHostname string + +resource origin 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: originGroup + name: originName + properties: { + hostName: originHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: originHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + } +} +``` + +## Application Code + +### Python +```python +# Origins are infrastructure — transparent to application code. +``` + +### C# +```csharp +// Origins are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Origins are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Origin host header**: Must match the backend's expected Host header. For App Service, use the `.azurewebsites.net` hostname. +- **HTTPS required**: Always use HTTPS for origin connections when possible. +- **Private Link for private origins**: Origins behind private endpoints need Private Link integration (Premium SKU). + +## Production Backlog Items +- Private Link origin connections for VNet-isolated backends +- Multi-region origins with priority-based failover +- Origin shield for reduced origin load diff --git a/azext_prototype/knowledge/services/cdn-security-policy.md b/azext_prototype/knowledge/services/cdn-security-policy.md new file mode 100644 index 0000000..ad93ea1 --- /dev/null +++ b/azext_prototype/knowledge/services/cdn-security-policy.md @@ -0,0 +1,111 @@ +--- +service_namespace: Microsoft.Cdn/profiles/securityPolicies +display_name: Front Door Security Policy (WAF Association) +depends_on: + - Microsoft.Cdn/profiles + - Microsoft.Cdn/profiles/afdEndpoints +--- + +# Front Door Security Policy + +> Associates a WAF policy with one or more Front Door endpoints. Enables web application firewall protection for incoming traffic. + +## When to Use +- Protect Front Door endpoints with WAF rules (OWASP, bot protection, custom rules) +- Required for production — recommended to configure early in POC +- One security policy can cover multiple endpoints + +## POC Defaults +- **WAF mode**: Detection (logs but doesn't block) — switch to Prevention for production +- **Managed rule sets**: Microsoft Default Rule Set (DRS 2.1) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "security_policy" { + type = "Microsoft.Cdn/profiles/securityPolicies@2024-02-01" + name = var.policy_name + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + parameters = { + type = "WebApplicationFirewall" + wafPolicy = { + id = azapi_resource.waf_policy.id + } + associations = [ + { + domains = [ + { id = azapi_resource.afd_endpoint.id } + ] + patternsToMatch = ["/*"] + } + ] + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Security policy management inherits from the parent CDN profile RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param policyName string +param wafPolicyId string +param endpointId string + +resource securityPolicy 'Microsoft.Cdn/profiles/securityPolicies@2024-02-01' = { + parent: cdnProfile + name: policyName + properties: { + parameters: { + type: 'WebApplicationFirewall' + wafPolicy: { id: wafPolicyId } + associations: [ + { + domains: [{ id: endpointId }] + patternsToMatch: ['/*'] + } + ] + } + } +} +``` + +## Application Code + +### Python +```python +# Security policies are infrastructure — transparent to application code. +# WAF blocks are returned as HTTP 403 responses to the client. +``` + +### C# +```csharp +// Security policies are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Security policies are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Detection vs Prevention**: In Detection mode, WAF logs threats but doesn't block them. Switch to Prevention for actual protection. +- **Domain association**: The security policy must be associated with specific endpoints. Without association, WAF rules don't apply. +- **WAF policy SKU**: The WAF policy must match the CDN profile SKU (Standard vs Premium). + +## Production Backlog Items +- Switch from Detection to Prevention mode +- Custom WAF rules for application-specific protection +- Bot management rules +- Rate limiting rules +- WAF log analysis via Log Analytics diff --git a/azext_prototype/knowledge/services/cdn.md b/azext_prototype/knowledge/services/cdn.md new file mode 100644 index 0000000..3bdadd3 --- /dev/null +++ b/azext_prototype/knowledge/services/cdn.md @@ -0,0 +1,333 @@ +--- +service_namespace: Microsoft.Cdn/profiles +display_name: Azure CDN / Front Door +--- + +# Azure CDN +> Global content delivery network for caching and accelerating static and dynamic content with edge locations worldwide. + +## When to Use + +- **Static content delivery** -- images, CSS, JavaScript, fonts served from edge locations close to users +- **Website acceleration** -- reduce latency for global web applications with dynamic site acceleration +- **Video streaming** -- large-scale media delivery with HTTP-based streaming +- **Software distribution** -- large file downloads distributed from edge PoPs +- **API acceleration** -- reduce latency for globally distributed API consumers + +Choose Azure CDN (Standard tier) for simple caching scenarios. Choose Azure Front Door (which uses `Microsoft.Cdn/profiles` with Premium tier) when you also need WAF, Private Link origins, or advanced routing. CDN profiles and Front Door profiles share the same ARM resource type. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard_AzureFrontDoor | Recommended over classic CDN SKUs | +| Origin type | Storage / App Service | Static or dynamic content origins | +| Caching | Enabled | Default caching rules for static content | +| Compression | Enabled | Gzip/Brotli for text-based content types | +| HTTPS | Required | HTTP-to-HTTPS redirect | +| Custom domain | Optional | Use CDN-provided endpoint for POC | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "cdn_profile" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.name + location = "global" + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # or "Standard_Microsoft" for classic CDN + } + } + + tags = var.tags +} + +resource "azapi_resource" "cdn_endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.endpoint_name + location = "global" + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + enabledState = "Enabled" + } + } + + tags = var.tags + + response_export_values = ["properties.hostName"] +} +``` + +### Origin Group and Origin + +```hcl +resource "azapi_resource" "origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = var.origin_group_name + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + additionalLatencyInMilliseconds = 50 + } + healthProbeSettings = { + probePath = "/health" + probeRequestType = "HEAD" + probeProtocol = "Https" + probeIntervalInSeconds = 30 + } + } + } +} + +resource "azapi_resource" "origin" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = var.origin_name + parent_id = azapi_resource.origin_group.id + + body = { + properties = { + hostName = var.origin_hostname # e.g., "mystorageaccount.blob.core.windows.net" + httpPort = 80 + httpsPort = 443 + originHostHeader = var.origin_hostname + priority = 1 + weight = 1000 + enabledState = "Enabled" + enforceCertificateNameCheck = true + } + } +} +``` + +### Route + +```hcl +resource "azapi_resource" "route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = var.route_name + parent_id = azapi_resource.cdn_endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.origin_group.id + } + supportedProtocols = ["Http", "Https"] + patternsToMatch = ["/*"] + forwardingProtocol = "HttpsOnly" + linkToDefaultDomain = "Enabled" + httpsRedirect = "Enabled" + cacheConfiguration = { + queryStringCachingBehavior = "IgnoreQueryString" + compressionSettings = { + isCompressionEnabled = true + contentTypesToCompress = [ + "text/html", + "text/css", + "application/javascript", + "application/json", + "image/svg+xml", + "application/xml" + ] + } + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# CDN Profile Contributor -- manage profiles, endpoints, and origins +resource "azapi_resource" "cdn_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.cdn_profile.id}${var.managed_identity_principal_id}cdn-contributor") + parent_id = azapi_resource.cdn_profile.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ec156ff8-a8d1-4d15-830c-5b80698ca432" # CDN Profile Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +CDN/Front Door Standard tier does not support Private Link origins. Private Link origins require Premium_AzureFrontDoor SKU: + +```hcl +# To use Private Link origins, upgrade to Premium_AzureFrontDoor SKU +# and configure the origin with privateLink settings: +# +# resource "azapi_resource" "origin" { +# body = { +# properties = { +# hostName = var.origin_hostname +# sharedPrivateLinkResource = { +# privateLink = { +# id = var.origin_resource_id +# } +# groupId = "blob" # or "sites", etc. +# privateLinkLocation = var.location +# requestMessage = "CDN Private Link" +# status = "Approved" +# } +# } +# } +# } +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the CDN profile') +param name string + +@description('Endpoint name') +param endpointName string + +@description('Origin hostname') +param originHostname string + +@description('Tags to apply') +param tags object = {} + +resource cdnProfile 'Microsoft.Cdn/profiles@2024-02-01' = { + name: name + location: 'global' + tags: tags + sku: { + name: 'Standard_AzureFrontDoor' + } +} + +resource endpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: cdnProfile + name: endpointName + location: 'global' + properties: { + enabledState: 'Enabled' + } +} + +resource originGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: cdnProfile + name: 'default-origin-group' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + additionalLatencyInMilliseconds: 50 + } + healthProbeSettings: { + probePath: '/health' + probeRequestType: 'HEAD' + probeProtocol: 'Https' + probeIntervalInSeconds: 30 + } + } +} + +resource origin 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: originGroup + name: 'primary-origin' + properties: { + hostName: originHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: originHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + enforceCertificateNameCheck: true + } +} + +resource route 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: endpoint + name: 'default-route' + properties: { + originGroup: { + id: originGroup.id + } + supportedProtocols: [ + 'Http' + 'Https' + ] + patternsToMatch: [ + '/*' + ] + forwardingProtocol: 'HttpsOnly' + linkToDefaultDomain: 'Enabled' + httpsRedirect: 'Enabled' + } + dependsOn: [ + origin // Origin must exist before route + ] +} + +output id string = cdnProfile.id +output endpointHostName string = endpoint.properties.hostName +``` + +### RBAC Assignment + +```bicep +@description('Principal ID for CDN management') +param principalId string + +resource cdnContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(cdnProfile.id, principalId, 'cdn-profile-contributor') + scope: cdnProfile + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ec156ff8-a8d1-4d15-830c-5b80698ca432') // CDN Profile Contributor + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Origin must exist before route | Deployment fails with dependency error | Use `dependsOn` or deploy origin before route | +| Propagation delay (10-20 min) | Changes not visible immediately at edge | Plan for propagation time during testing | +| Cache invalidation costs | Purge operations have rate limits | Use versioned URLs (`?v=2`) instead of frequent purges | +| Missing origin host header | Origin receives wrong Host header; returns 404 | Set `originHostHeader` to match origin's expected hostname | +| Classic CDN vs Front Door CDN confusion | Different capabilities and API shapes | Use `Standard_AzureFrontDoor` SKU for new deployments | +| CORS not configured on origin | Browser blocks cross-origin requests | Configure CORS headers on the origin, not the CDN | +| Custom domain DNS validation | Domain not verified; HTTPS fails | Complete DNS CNAME validation before enabling custom domain | +| Compression disabled by default | Larger payloads; higher bandwidth costs | Enable compression and specify content types to compress | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Custom domain with TLS | P2 | Bind custom domain with managed or BYOC certificate | +| WAF policy | P1 | Upgrade to Premium and configure WAF rules for OWASP protection | +| Private Link origins | P1 | Use Premium tier to connect to origins via private endpoints | +| Geo-filtering | P3 | Restrict content delivery to specific countries/regions | +| Rules engine | P2 | Configure URL rewrite, redirect, and header modification rules | +| Monitoring and alerts | P2 | Set up alerts for origin health, cache hit ratio, and bandwidth | +| Cache optimization | P3 | Tune caching rules per content type and path patterns | +| Multi-origin failover | P2 | Configure multiple origins with health probes for HA | +| DDoS protection | P2 | Enable Azure DDoS Protection on the CDN profile | +| Analytics | P3 | Enable CDN analytics for traffic patterns and usage reporting | diff --git a/azext_prototype/knowledge/services/cognitive-services-deployment.md b/azext_prototype/knowledge/services/cognitive-services-deployment.md new file mode 100644 index 0000000..701ba80 --- /dev/null +++ b/azext_prototype/knowledge/services/cognitive-services-deployment.md @@ -0,0 +1,148 @@ +--- +service_namespace: Microsoft.CognitiveServices/accounts/deployments +display_name: Cognitive Services / OpenAI Model Deployment +depends_on: + - Microsoft.CognitiveServices/accounts +--- + +# Cognitive Services Model Deployment + +> Deploys a specific AI model (GPT-4, GPT-3.5-turbo, text-embedding-ada-002, etc.) within a Cognitive Services or Azure OpenAI account. + +## When to Use +- Every Azure OpenAI application needs at least one model deployment +- Deploy different models for different tasks (chat, embeddings, completions) +- Control capacity allocation per model via TPM (tokens per minute) + +## POC Defaults +- **Model**: gpt-4o or gpt-4o-mini for chat; text-embedding-3-small for embeddings +- **Capacity**: 10K TPM (tokens per minute) — sufficient for POC +- **SKU**: Standard + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "openai_deployment" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-10-01" + name = var.deployment_name + parent_id = azapi_resource.openai_account.id + + body = { + sku = { + name = "Standard" + capacity = 10 + } + properties = { + model = { + format = "OpenAI" + name = var.model_name # e.g., "gpt-4o" + version = var.model_version # e.g., "2024-08-06" + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Model deployment access is granted at the account level: +# Cognitive Services OpenAI User: 5e0bd9bd-7b93-4f28-af87-19fc36ad61bd +# Cognitive Services OpenAI Contributor: a001fd3d-188f-4b5d-821b-7da978bf7442 +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param deploymentName string +param modelName string +param modelVersion string + +resource deployment 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { + parent: openaiAccount + name: deploymentName + sku: { + name: 'Standard' + capacity: 10 + } + properties: { + model: { + format: 'OpenAI' + name: modelName + version: modelVersion + } + } +} +``` + +## Application Code + +### Python +```python +from openai import AzureOpenAI +from azure.identity import DefaultAzureCredential, get_bearer_token_provider + +credential = DefaultAzureCredential() +token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default") + +client = AzureOpenAI( + azure_endpoint="https://.openai.azure.com/", + azure_ad_token_provider=token_provider, + api_version="2024-08-01-preview" +) + +response = client.chat.completions.create( + model=deployment_name, + messages=[{"role": "user", "content": "Hello"}] +) +print(response.choices[0].message.content) +``` + +### C# +```csharp +using Azure.Identity; +using Azure.AI.OpenAI; + +var credential = new DefaultAzureCredential(); +var client = new AzureOpenAIClient( + new Uri("https://.openai.azure.com/"), credential); + +var chatClient = client.GetChatClient(deploymentName); +var response = await chatClient.CompleteChatAsync( + new[] { new UserChatMessage("Hello") }); +Console.WriteLine(response.Value.Content[0].Text); +``` + +### Node.js +```typescript +import { AzureOpenAI } from "openai"; +import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const tokenProvider = getBearerTokenProvider(credential, "https://cognitiveservices.azure.com/.default"); + +const client = new AzureOpenAI({ + azureADTokenProvider: tokenProvider, + endpoint: "https://.openai.azure.com/", + apiVersion: "2024-08-01-preview", +}); + +const response = await client.chat.completions.create({ + model: deploymentName, + messages: [{ role: "user", content: "Hello" }], +}); +console.log(response.choices[0].message.content); +``` + +## Common Pitfalls +- **Model availability varies by region**: Not all models are available in all regions. Check regional availability before deployment. +- **Capacity is shared per model**: TPM capacity is shared across all deployments of the same model in the same account. +- **Deployment name != model name**: The deployment name is user-defined; the model name is the Azure-internal model identifier (e.g., `gpt-4o`). +- **API version matters**: Different API versions support different features. Use the latest stable version. + +## Production Backlog Items +- Content filtering configuration for responsible AI +- Provisioned throughput for guaranteed capacity +- Multiple deployments for A/B testing different models +- Rate limiting and quota management diff --git a/azext_prototype/knowledge/services/cognitive-services.md b/azext_prototype/knowledge/services/cognitive-services.md index 8aeccc1..51a1d2e 100644 --- a/azext_prototype/knowledge/services/cognitive-services.md +++ b/azext_prototype/knowledge/services/cognitive-services.md @@ -1,372 +1,442 @@ -# Azure OpenAI Service / Cognitive Services -> Managed AI platform for deploying OpenAI models (GPT-4o, GPT-4, GPT-3.5, DALL-E, Whisper, embeddings) and Azure AI services with enterprise security and compliance. - -## When to Use - -- **Generative AI** -- text generation, summarization, translation, code generation via GPT models -- **Chat applications** -- conversational AI with system prompts, function calling, and structured outputs -- **Embeddings** -- vector representations for semantic search, RAG patterns, and similarity matching -- **Image generation** -- DALL-E models for image creation from text prompts -- **Speech** -- Whisper models for speech-to-text transcription -- **RAG (Retrieval-Augmented Generation)** -- combine with Azure AI Search for grounded responses - -Azure OpenAI is the preferred path for enterprise AI workloads. It provides the same models as OpenAI with Azure's security, networking, and compliance guarantees. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Account kind | OpenAI | For Azure OpenAI models | -| Account SKU | S0 | Standard tier; all features available | -| Model deployment | Separate resource | CRITICAL: Model deployments are separate from the account | -| Default model | gpt-4o | Best balance of capability and cost for POC | -| Embeddings model | text-embedding-ada-002 | Or text-embedding-3-small for newer workloads | -| Public network access | Enabled (POC) | Flag private endpoint as production backlog item | -| Local auth | Disabled | Use AAD authentication via managed identity | - -**CRITICAL:** Model deployments are **separate resources** from the Cognitive Services account. Creating the account alone does not give you a usable model -- you must also deploy one or more models. - -**CRITICAL:** Regional availability varies significantly by model. Not all models are available in all regions. Check [Azure OpenAI model availability](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) before selecting a region. - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_cognitive_account" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - kind = "OpenAI" - sku_name = "S0" - custom_subdomain_name = var.name # Required for token-based auth - public_network_access_enabled = true # Set false when using private endpoint - local_auth_enabled = false # CRITICAL: Disable key-based auth - - identity { - type = "SystemAssigned" - } - - tags = var.tags -} - -# Model deployment -- CRITICAL: separate resource -resource "azurerm_cognitive_deployment" "gpt4o" { - name = "gpt-4o" - cognitive_account_id = azurerm_cognitive_account.this.id - - model { - format = "OpenAI" - name = "gpt-4o" - version = "2024-11-20" - } - - sku { - name = "Standard" - capacity = 10 # Thousands of tokens per minute (TPM) - } -} - -# Embeddings deployment -resource "azurerm_cognitive_deployment" "embeddings" { - name = "text-embedding-3-small" - cognitive_account_id = azurerm_cognitive_account.this.id - - model { - format = "OpenAI" - name = "text-embedding-3-small" - version = "1" - } - - sku { - name = "Standard" - capacity = 120 # TPM - } -} -``` - -### RBAC Assignment - -```hcl -# Cognitive Services User -- invoke models (inference) -resource "azurerm_role_assignment" "openai_user" { - scope = azurerm_cognitive_account.this.id - role_definition_name = "Cognitive Services User" - principal_id = var.managed_identity_principal_id -} - -# Cognitive Services Contributor -- manage deployments and account settings -resource "azurerm_role_assignment" "openai_contributor" { - scope = azurerm_cognitive_account.this.id - role_definition_name = "Cognitive Services Contributor" - principal_id = var.admin_identity_principal_id -} - -# Cognitive Services OpenAI User -- specific to OpenAI operations (alternative to generic User) -resource "azurerm_role_assignment" "openai_specific_user" { - scope = azurerm_cognitive_account.this.id - role_definition_name = "Cognitive Services OpenAI User" - principal_id = var.managed_identity_principal_id -} -``` - -RBAC role IDs: -- Cognitive Services User: `a97b65f3-24c7-4388-baec-2e87135dc908` -- Cognitive Services Contributor: `25fbc0a9-bd7c-42a3-aa1a-3b75d497ee68` -- Cognitive Services OpenAI User: `5e0bd9bd-7b93-4f28-af87-19fc36ad61bd` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "openai" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_cognitive_account.this.id - subresource_names = ["account"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.openai.azure.com` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Azure OpenAI account') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Tags to apply') -param tags object = {} - -resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = { - name: name - location: location - tags: tags - kind: 'OpenAI' - sku: { - name: 'S0' - } - identity: { - type: 'SystemAssigned' - } - properties: { - customSubDomainName: name - publicNetworkAccess: 'Enabled' // Set 'Disabled' when using private endpoint - disableLocalAuth: true // CRITICAL: Disable key-based auth - } -} - -// Model deployment -- CRITICAL: separate resource -resource gpt4o 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { - parent: openai - name: 'gpt-4o' - sku: { - name: 'Standard' - capacity: 10 - } - properties: { - model: { - format: 'OpenAI' - name: 'gpt-4o' - version: '2024-11-20' - } - } -} - -resource embeddings 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { - parent: openai - name: 'text-embedding-3-small' - sku: { - name: 'Standard' - capacity: 120 - } - properties: { - model: { - format: 'OpenAI' - name: 'text-embedding-3-small' - version: '1' - } - } - dependsOn: [gpt4o] // Deploy sequentially to avoid conflicts -} - -output id string = openai.id -output name string = openai.name -output endpoint string = openai.properties.endpoint -output principalId string = openai.identity.principalId -``` - -### RBAC Assignment - -```bicep -@description('Principal ID of the managed identity for model inference') -param principalId string - -var cognitiveServicesUserRoleId = 'a97b65f3-24c7-4388-baec-2e87135dc908' - -resource userRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(openai.id, principalId, cognitiveServicesUserRoleId) - scope: openai - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', cognitiveServicesUserRoleId) - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python - -```python -from openai import AzureOpenAI -from azure.identity import DefaultAzureCredential, get_bearer_token_provider - -credential = DefaultAzureCredential(managed_identity_client_id="") -token_provider = get_bearer_token_provider( - credential, "https://cognitiveservices.azure.com/.default" -) - -client = AzureOpenAI( - azure_endpoint="https://myopenai.openai.azure.com", - azure_ad_token_provider=token_provider, - api_version="2024-10-21", -) - -# Chat completion -response = client.chat.completions.create( - model="gpt-4o", # Deployment name, not model name - messages=[ - {"role": "system", "content": "You are a helpful assistant."}, - {"role": "user", "content": "Hello!"}, - ], - temperature=0.7, - max_tokens=1000, -) -print(response.choices[0].message.content) - -# Embeddings -embedding_response = client.embeddings.create( - model="text-embedding-3-small", # Deployment name - input="The quick brown fox jumps over the lazy dog", -) -vector = embedding_response.data[0].embedding -``` - -### C# / .NET - -```csharp -using Azure.Identity; -using Azure.AI.OpenAI; -using OpenAI.Chat; - -var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions -{ - ManagedIdentityClientId = "" -}); - -var client = new AzureOpenAIClient( - new Uri("https://myopenai.openai.azure.com"), - credential -); - -// Chat completion -var chatClient = client.GetChatClient("gpt-4o"); // Deployment name -var response = await chatClient.CompleteChatAsync( - new List - { - new SystemChatMessage("You are a helpful assistant."), - new UserChatMessage("Hello!") - }, - new ChatCompletionOptions - { - Temperature = 0.7f, - MaxOutputTokenCount = 1000 - } -); - -Console.WriteLine(response.Value.Content[0].Text); -``` - -### Node.js - -```typescript -import { AzureOpenAI } from "openai"; -import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity"; - -const credential = new DefaultAzureCredential({ - managedIdentityClientId: "", -}); - -const scope = "https://cognitiveservices.azure.com/.default"; -const azureADTokenProvider = getBearerTokenProvider(credential, scope); - -const client = new AzureOpenAI({ - azureADTokenProvider, - endpoint: "https://myopenai.openai.azure.com", - apiVersion: "2024-10-21", - deployment: "gpt-4o", -}); - -// Chat completion -const response = await client.chat.completions.create({ - model: "gpt-4o", - messages: [ - { role: "system", content: "You are a helpful assistant." }, - { role: "user", content: "Hello!" }, - ], - temperature: 0.7, - max_tokens: 1000, -}); - -console.log(response.choices[0].message.content); -``` - -## Common Pitfalls - -1. **Model deployments are separate resources** -- Creating the Cognitive Services account alone is not enough. You must explicitly deploy models (GPT-4o, embeddings, etc.) as child resources. Without deployments, API calls fail with 404. -2. **Regional availability** -- Not all models are available in all regions. GPT-4o may be available in East US but not West Europe. Always check model availability before choosing a region. -3. **Deployment name vs model name** -- In SDK calls, use the **deployment name** (the name you gave when deploying), not the model name. These can differ. -4. **Token scope** -- Always use `https://cognitiveservices.azure.com/.default` as the token scope, not a service-specific URL. This scope covers all Cognitive Services including OpenAI. -5. **Rate limiting (TPM)** -- Token-per-minute (TPM) limits are set per deployment. A capacity of 10 means 10K TPM. Exceeding the limit returns 429 errors. Implement retry with exponential backoff. -6. **Content filtering** -- Azure OpenAI applies content filtering by default. Requests or responses flagged by the content filter return 400 errors. This cannot be fully disabled. -7. **Custom subdomain required** -- The `custom_subdomain_name` property is required for AAD authentication. Without it, only key-based auth works (which is prohibited by governance policies). -8. **Sequential model deployments** -- In Bicep, deploy models sequentially (use `dependsOn`) to avoid conflicts. Concurrent deployment operations on the same account can fail. -9. **Quota limits** -- TPM quotas are shared per subscription per region. Multiple deployments in the same region share the same quota pool. - -## Production Backlog Items - -- [ ] Configure private endpoint and disable public network access -- [ ] Review and configure content filtering policies for the specific use case -- [ ] Implement rate limiting and retry logic in application code -- [ ] Set up provisioned throughput (PTU) for predictable latency and cost -- [ ] Configure monitoring alerts for token usage, latency, and error rates -- [ ] Implement prompt caching and response caching where appropriate -- [ ] Set up logging for audit and compliance (Azure Monitor diagnostic settings) -- [ ] Review model versions and plan for model version upgrades -- [ ] Implement fallback logic for multi-region deployments (handle regional outages) -- [ ] Configure network ACLs to restrict access to known IP ranges or VNets +--- +service_namespace: Microsoft.CognitiveServices/accounts#cognitive +display_name: Azure Cognitive Services +--- + +# Azure OpenAI Service / Cognitive Services +> Managed AI platform for deploying OpenAI models (GPT-4o, GPT-4, GPT-3.5, DALL-E, Whisper, embeddings) and Azure AI services with enterprise security and compliance. + +## When to Use + +- **Generative AI** -- text generation, summarization, translation, code generation via GPT models +- **Chat applications** -- conversational AI with system prompts, function calling, and structured outputs +- **Embeddings** -- vector representations for semantic search, RAG patterns, and similarity matching +- **Image generation** -- DALL-E models for image creation from text prompts +- **Speech** -- Whisper models for speech-to-text transcription +- **RAG (Retrieval-Augmented Generation)** -- combine with Azure AI Search for grounded responses + +Azure OpenAI is the preferred path for enterprise AI workloads. It provides the same models as OpenAI with Azure's security, networking, and compliance guarantees. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Account kind | OpenAI | For Azure OpenAI models | +| Account SKU | S0 | Standard tier; all features available | +| Model deployment | Separate resource | CRITICAL: Model deployments are separate from the account | +| Default model | gpt-4o | Best balance of capability and cost for POC | +| Embeddings model | text-embedding-ada-002 | Or text-embedding-3-small for newer workloads | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | +| Local auth | Disabled | Use AAD authentication via managed identity | + +**CRITICAL:** Model deployments are **separate resources** from the Cognitive Services account. Creating the account alone does not give you a usable model -- you must also deploy one or more models. + +**CRITICAL:** Regional availability varies significantly by model. Not all models are available in all regions. Check [Azure OpenAI model availability](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) before selecting a region. + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "openai" { + type = "Microsoft.CognitiveServices/accounts@2024-10-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + kind = "OpenAI" + sku = { + name = "S0" + } + properties = { + customSubDomainName = var.name # Required for token-based auth + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + disableLocalAuth = true # CRITICAL: Disable key-based auth + } + } + + tags = var.tags + + response_export_values = ["properties.endpoint"] +} + +# Model deployment -- CRITICAL: separate resource +resource "azapi_resource" "gpt4o" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-10-01" + name = "gpt-4o" + parent_id = azapi_resource.openai.id + + body = { + sku = { + name = "Standard" + capacity = 10 # Thousands of tokens per minute (TPM) + } + properties = { + model = { + format = "OpenAI" + name = "gpt-4o" + version = "2024-11-20" + } + } + } +} + +# Embeddings deployment +resource "azapi_resource" "embeddings" { + type = "Microsoft.CognitiveServices/accounts/deployments@2024-10-01" + name = "text-embedding-3-small" + parent_id = azapi_resource.openai.id + + body = { + sku = { + name = "Standard" + capacity = 120 # TPM + } + properties = { + model = { + format = "OpenAI" + name = "text-embedding-3-small" + version = "1" + } + } + } + + depends_on = [azapi_resource.gpt4o] # Deploy sequentially to avoid conflicts +} +``` + +### RBAC Assignment + +```hcl +# Cognitive Services User -- invoke models (inference) +resource "azapi_resource" "openai_user_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.openai.id}${var.managed_identity_principal_id}cs-user") + parent_id = azapi_resource.openai.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/a97b65f3-24c7-4388-baec-2e87135dc908" # Cognitive Services User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Cognitive Services Contributor -- manage deployments and account settings +resource "azapi_resource" "openai_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.openai.id}${var.admin_identity_principal_id}cs-contributor") + parent_id = azapi_resource.openai.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/25fbc0a9-bd7c-42a3-aa1a-3b75d497ee68" # Cognitive Services Contributor + principalId = var.admin_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Cognitive Services OpenAI User -- specific to OpenAI operations (alternative to generic User) +resource "azapi_resource" "openai_specific_user_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.openai.id}${var.managed_identity_principal_id}cs-openai-user") + parent_id = azapi_resource.openai.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/5e0bd9bd-7b93-4f28-af87-19fc36ad61bd" # Cognitive Services OpenAI User + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +RBAC role IDs: +- Cognitive Services User: `a97b65f3-24c7-4388-baec-2e87135dc908` +- Cognitive Services Contributor: `25fbc0a9-bd7c-42a3-aa1a-3b75d497ee68` +- Cognitive Services OpenAI User: `5e0bd9bd-7b93-4f28-af87-19fc36ad61bd` + +### Private Endpoint + +```hcl +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.openai.id + groupIds = ["account"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.openai.azure.com` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Azure OpenAI account') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource openai 'Microsoft.CognitiveServices/accounts@2024-10-01' = { + name: name + location: location + tags: tags + kind: 'OpenAI' + sku: { + name: 'S0' + } + identity: { + type: 'SystemAssigned' + } + properties: { + customSubDomainName: name + publicNetworkAccess: 'Disabled' // Unless told otherwise, disabled per governance policy + disableLocalAuth: true // CRITICAL: Disable key-based auth + } +} + +// Model deployment -- CRITICAL: separate resource +resource gpt4o 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { + parent: openai + name: 'gpt-4o' + sku: { + name: 'Standard' + capacity: 10 + } + properties: { + model: { + format: 'OpenAI' + name: 'gpt-4o' + version: '2024-11-20' + } + } +} + +resource embeddings 'Microsoft.CognitiveServices/accounts/deployments@2024-10-01' = { + parent: openai + name: 'text-embedding-3-small' + sku: { + name: 'Standard' + capacity: 120 + } + properties: { + model: { + format: 'OpenAI' + name: 'text-embedding-3-small' + version: '1' + } + } + dependsOn: [gpt4o] // Deploy sequentially to avoid conflicts +} + +output id string = openai.id +output name string = openai.name +output endpoint string = openai.properties.endpoint +output principalId string = openai.identity.principalId +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity for model inference') +param principalId string + +var cognitiveServicesUserRoleId = 'a97b65f3-24c7-4388-baec-2e87135dc908' + +resource userRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(openai.id, principalId, cognitiveServicesUserRoleId) + scope: openai + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', cognitiveServicesUserRoleId) + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python + +```python +from openai import AzureOpenAI +from azure.identity import DefaultAzureCredential, get_bearer_token_provider + +credential = DefaultAzureCredential(managed_identity_client_id="") +token_provider = get_bearer_token_provider( + credential, "https://cognitiveservices.azure.com/.default" +) + +client = AzureOpenAI( + azure_endpoint="https://myopenai.openai.azure.com", + azure_ad_token_provider=token_provider, + api_version="2024-10-21", +) + +# Chat completion +response = client.chat.completions.create( + model="gpt-4o", # Deployment name, not model name + messages=[ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": "Hello!"}, + ], + temperature=0.7, + max_tokens=1000, +) +print(response.choices[0].message.content) + +# Embeddings +embedding_response = client.embeddings.create( + model="text-embedding-3-small", # Deployment name + input="The quick brown fox jumps over the lazy dog", +) +vector = embedding_response.data[0].embedding +``` + +### C# / .NET + +```csharp +using Azure.Identity; +using Azure.AI.OpenAI; +using OpenAI.Chat; + +var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions +{ + ManagedIdentityClientId = "" +}); + +var client = new AzureOpenAIClient( + new Uri("https://myopenai.openai.azure.com"), + credential +); + +// Chat completion +var chatClient = client.GetChatClient("gpt-4o"); // Deployment name +var response = await chatClient.CompleteChatAsync( + new List + { + new SystemChatMessage("You are a helpful assistant."), + new UserChatMessage("Hello!") + }, + new ChatCompletionOptions + { + Temperature = 0.7f, + MaxOutputTokenCount = 1000 + } +); + +Console.WriteLine(response.Value.Content[0].Text); +``` + +### Node.js + +```typescript +import { AzureOpenAI } from "openai"; +import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity"; + +const credential = new DefaultAzureCredential({ + managedIdentityClientId: "", +}); + +const scope = "https://cognitiveservices.azure.com/.default"; +const azureADTokenProvider = getBearerTokenProvider(credential, scope); + +const client = new AzureOpenAI({ + azureADTokenProvider, + endpoint: "https://myopenai.openai.azure.com", + apiVersion: "2024-10-21", + deployment: "gpt-4o", +}); + +// Chat completion +const response = await client.chat.completions.create({ + model: "gpt-4o", + messages: [ + { role: "system", content: "You are a helpful assistant." }, + { role: "user", content: "Hello!" }, + ], + temperature: 0.7, + max_tokens: 1000, +}); + +console.log(response.choices[0].message.content); +``` + +## Common Pitfalls + +1. **Model deployments are separate resources** -- Creating the Cognitive Services account alone is not enough. You must explicitly deploy models (GPT-4o, embeddings, etc.) as child resources. Without deployments, API calls fail with 404. +2. **Regional availability** -- Not all models are available in all regions. GPT-4o may be available in East US but not West Europe. Always check model availability before choosing a region. +3. **Deployment name vs model name** -- In SDK calls, use the **deployment name** (the name you gave when deploying), not the model name. These can differ. +4. **Token scope** -- Always use `https://cognitiveservices.azure.com/.default` as the token scope, not a service-specific URL. This scope covers all Cognitive Services including OpenAI. +5. **Rate limiting (TPM)** -- Token-per-minute (TPM) limits are set per deployment. A capacity of 10 means 10K TPM. Exceeding the limit returns 429 errors. Implement retry with exponential backoff. +6. **Content filtering** -- Azure OpenAI applies content filtering by default. Requests or responses flagged by the content filter return 400 errors. This cannot be fully disabled. +7. **Custom subdomain required** -- The `custom_subdomain_name` property is required for AAD authentication. Without it, only key-based auth works (which is prohibited by governance policies). +8. **Sequential model deployments** -- In Bicep, deploy models sequentially (use `dependsOn`) to avoid conflicts. Concurrent deployment operations on the same account can fail. +9. **Quota limits** -- TPM quotas are shared per subscription per region. Multiple deployments in the same region share the same quota pool. + +## Production Backlog Items + +- [ ] Configure private endpoint and disable public network access +- [ ] Review and configure content filtering policies for the specific use case +- [ ] Implement rate limiting and retry logic in application code +- [ ] Set up provisioned throughput (PTU) for predictable latency and cost +- [ ] Configure monitoring alerts for token usage, latency, and error rates +- [ ] Implement prompt caching and response caching where appropriate +- [ ] Set up logging for audit and compliance (Azure Monitor diagnostic settings) +- [ ] Review model versions and plan for model version upgrades +- [ ] Implement fallback logic for multi-region deployments (handle regional outages) +- [ ] Configure network ACLs to restrict access to known IP ranges or VNets diff --git a/azext_prototype/knowledge/services/communication-email-domain.md b/azext_prototype/knowledge/services/communication-email-domain.md new file mode 100644 index 0000000..05fead8 --- /dev/null +++ b/azext_prototype/knowledge/services/communication-email-domain.md @@ -0,0 +1,131 @@ +--- +service_namespace: Microsoft.Communication/emailServices/domains +display_name: Communication Email Domain +depends_on: + - Microsoft.Communication/emailServices +--- + +# Communication Email Domain + +> Custom or Azure-managed email domain configuration within an ACS Email Service, controlling sender addresses, DKIM/SPF verification, and sender authentication for email delivery. + +## When to Use +- **Custom domain sending** -- send from `noreply@yourcompany.com` instead of the Azure-managed domain +- **Brand consistency** -- emails appear from your own domain, improving trust and open rates +- **Compliance requirements** -- certain industries require email from a verified corporate domain +- **Azure-managed domain (POC)** -- use the built-in `*.azurecomm.net` domain for quick POC setup + +Every email service automatically provisions an Azure-managed domain. Custom domains require DNS verification (DKIM, SPF, DMARC). + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Domain management | AzureManagedDomain | Automatic for POC; no DNS changes needed | +| User engagement tracking | Disabled | Enable for production analytics | +| Sender username | DoNotReply | Default sender on managed domain | + +## Terraform Patterns + +### Basic Resource + +```hcl +# Azure-managed domain (created automatically, but can be explicit) +resource "azapi_resource" "managed_domain" { + type = "Microsoft.Communication/emailServices/domains@2023-04-01" + name = "AzureManagedDomain" + parent_id = azapi_resource.email_service.id + location = "global" + + body = { + properties = { + domainManagement = "AzureManagedDomain" + userEngagementTracking = "Disabled" + } + } + + response_export_values = ["properties.fromSenderDomain", "properties.mailFromSenderDomain"] +} + +# Custom domain +resource "azapi_resource" "custom_domain" { + type = "Microsoft.Communication/emailServices/domains@2023-04-01" + name = var.custom_domain_name # e.g., "contoso.com" + parent_id = azapi_resource.email_service.id + location = "global" + + body = { + properties = { + domainManagement = "CustomerManaged" + userEngagementTracking = "Disabled" + } + } + + response_export_values = ["properties.verificationStates"] +} +``` + +### RBAC Assignment + +```hcl +# Domain management inherits from the parent email service RBAC. +# Contributor on the email service covers domain operations. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Custom domain name (e.g., contoso.com)') +param domainName string + +@description('Domain management type') +@allowed(['AzureManagedDomain', 'CustomerManaged', 'CustomerManagedInExchangeOnline']) +param domainManagement string = 'AzureManagedDomain' + +resource domain 'Microsoft.Communication/emailServices/domains@2023-04-01' = { + parent: emailService + name: domainManagement == 'AzureManagedDomain' ? 'AzureManagedDomain' : domainName + location: 'global' + properties: { + domainManagement: domainManagement + userEngagementTracking: 'Disabled' + } +} + +output domainId string = domain.id +output fromSenderDomain string = domain.properties.fromSenderDomain +output mailFromSenderDomain string = domain.properties.mailFromSenderDomain +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. The domain configuration determines which sender addresses are available; application code references the sender address directly in the `EmailMessage`. + +### C# +Infrastructure -- transparent to application code. The domain configuration determines which sender addresses are available; application code references the sender address directly in the `EmailMessage`. + +### Node.js +Infrastructure -- transparent to application code. The domain configuration determines which sender addresses are available; application code references the sender address directly in the `EmailMessage`. + +## Common Pitfalls + +1. **Azure-managed domain name must be exactly `"AzureManagedDomain"`** -- Using any other name for the managed domain type causes deployment failure. +2. **Custom domain DNS verification is manual** -- After deploying a `CustomerManaged` domain, you must add DKIM, SPF, and DMARC TXT records to your DNS zone. The domain remains `NotStarted` until verified. +3. **DKIM has three verification records** -- Unlike typical email setups, ACS requires three CNAME records for DKIM. Missing any one blocks verification. +4. **Domain must be linked to ACS resource** -- After domain creation and verification, the domain must be linked to the parent Communication Services resource before it can be used for sending. +5. **Sender usernames must be provisioned** -- Custom domains require explicit sender username resources (`Microsoft.Communication/emailServices/domains/senderUsernames`) before you can send from an address. +6. **Engagement tracking affects DNS** -- Enabling `userEngagementTracking` requires additional DNS records for click/open tracking. Deploy without tracking first, add later. +7. **Verification timeout** -- Custom domain verification must be completed within 7 days of resource creation. After that, delete and recreate. + +## Production Backlog Items + +- [ ] Configure custom domain with full DKIM, SPF, and DMARC DNS records +- [ ] Verify custom domain and confirm `VerificationStatus` is `Verified` for all record types +- [ ] Create sender username resources for all required sending addresses +- [ ] Enable user engagement tracking with appropriate DNS records +- [ ] Link verified domain to the parent Communication Services resource +- [ ] Set up DMARC reporting to monitor email authentication failures +- [ ] Plan domain verification for any additional sending domains diff --git a/azext_prototype/knowledge/services/communication-email-service.md b/azext_prototype/knowledge/services/communication-email-service.md new file mode 100644 index 0000000..9f865b1 --- /dev/null +++ b/azext_prototype/knowledge/services/communication-email-service.md @@ -0,0 +1,196 @@ +--- +service_namespace: Microsoft.Communication/emailServices +display_name: Azure Communication Services Email +--- + +# Azure Communication Services Email + +> Managed email sending service within Azure Communication Services, enabling applications to send transactional and bulk emails with high deliverability, DKIM/SPF authentication, and tracking. + +## When to Use +- **Transactional email** -- order confirmations, password resets, notifications from your application +- **Bulk email** -- marketing campaigns, newsletters with engagement tracking +- **Azure-native email** -- tighter integration with other ACS capabilities (SMS, chat, voice) +- **Custom domain sending** -- send from your own domain with full DKIM, SPF, DMARC authentication + +Choose ACS Email over SendGrid when you want a fully Azure-native solution without third-party dependencies. Choose SendGrid for its more mature template engine and analytics dashboard. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Data location | United States | Or appropriate geography for compliance | +| Domain type | AzureManagedDomain | Free Azure-managed `*.azurecomm.net` domain for POC | +| Custom domain | Optional | Add for production with DKIM/SPF | +| Sender address | `DoNotReply@.azurecomm.net` | Default sender on managed domain | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "email_service" { + type = "Microsoft.Communication/emailServices@2023-04-01" + name = var.name + location = "global" # Email services are global resources + parent_id = var.resource_group_id + + body = { + properties = { + dataLocation = var.data_location # e.g., "United States" + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### RBAC Assignment + +```hcl +# Contributor on the email service for management +resource "azapi_resource" "email_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.email_service.id}-${var.principal_id}-contributor") + parent_id = azapi_resource.email_service.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" + principalId = var.principal_id + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the email service') +param name string + +@description('Data residency location') +@allowed(['United States', 'Europe', 'Asia Pacific', 'Australia', 'UK', 'Japan', 'France', 'Germany']) +param dataLocation string = 'United States' + +param tags object = {} + +resource emailService 'Microsoft.Communication/emailServices@2023-04-01' = { + name: name + location: 'global' + tags: tags + properties: { + dataLocation: dataLocation + } +} + +output id string = emailService.id +output name string = emailService.name +``` + +## Application Code + +### Python + +```python +from azure.communication.email import EmailClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = EmailClient( + endpoint="https://.communication.azure.com", + credential=credential +) + +message = { + "senderAddress": "DoNotReply@.azurecomm.net", + "recipients": { + "to": [{"address": "user@example.com", "displayName": "Recipient"}] + }, + "content": { + "subject": "Welcome to our service", + "plainText": "Hello from Azure Communication Services Email.", + "html": "

Hello

Welcome to our service.

" + } +} + +poller = client.begin_send(message) +result = poller.result() +print(f"Message ID: {result.id}, Status: {result.status}") +``` + +### C# + +```csharp +using Azure.Communication.Email; +using Azure.Identity; + +var client = new EmailClient( + new Uri("https://.communication.azure.com"), + new DefaultAzureCredential()); + +var emailMessage = new EmailMessage( + senderAddress: "DoNotReply@.azurecomm.net", + recipientAddress: "user@example.com", + content: new EmailContent("Welcome") + { + PlainText = "Hello from Azure Communication Services Email.", + Html = "

Hello

Welcome to our service.

" + }); + +EmailSendOperation operation = await client.SendAsync( + WaitUntil.Completed, emailMessage); +Console.WriteLine($"Status: {operation.Value.Status}"); +``` + +### Node.js + +```typescript +import { EmailClient } from "@azure/communication-email"; +import { DefaultAzureCredential } from "@azure/identity"; + +const client = new EmailClient( + "https://.communication.azure.com", + new DefaultAzureCredential() +); + +const message = { + senderAddress: "DoNotReply@.azurecomm.net", + recipients: { + to: [{ address: "user@example.com", displayName: "Recipient" }], + }, + content: { + subject: "Welcome to our service", + plainText: "Hello from Azure Communication Services Email.", + html: "

Hello

Welcome to our service.

", + }, +}; + +const poller = await client.beginSend(message); +const result = await poller.pollUntilDone(); +console.log(`Message ID: ${result.id}, Status: ${result.status}`); +``` + +## Common Pitfalls + +1. **Location must be `"global"`** -- Email services are global resources. Specifying a region like `eastus` causes deployment failure. +2. **Data location vs resource location** -- `location` is always `global`, but `dataLocation` controls where data is stored for compliance (e.g., `United States`, `Europe`). +3. **Azure-managed domain limitations** -- The `*.azurecomm.net` domain has sending limits and cannot be customized. Use a custom domain for production. +4. **Linking to Communication Services** -- The email service must be linked to an ACS resource via `Microsoft.Communication/communicationServices` linked domains before sending. +5. **Asynchronous sending** -- `begin_send()` returns a poller. Emails are queued and may take seconds to minutes for delivery. Check the operation status. +6. **Rate limits** -- Default rate limits are 30 messages/minute and 100 recipients/hour for new services. Request increases via support. +7. **DKIM/SPF for custom domains** -- Custom domains require DNS TXT records for DKIM and SPF verification. Incomplete verification blocks sending from that domain. + +## Production Backlog Items + +- [ ] Configure custom sending domain with DKIM, SPF, and DMARC authentication +- [ ] Request sending limit increases based on projected volume +- [ ] Set up suppression list management for bounced addresses +- [ ] Implement email tracking (open, click) via engagement tracking +- [ ] Configure diagnostic logging to Log Analytics for delivery monitoring +- [ ] Add email templates for consistent branding across transactional emails +- [ ] Plan IP warm-up strategy if sending high-volume email from new domain diff --git a/azext_prototype/knowledge/services/communication-services.md b/azext_prototype/knowledge/services/communication-services.md new file mode 100644 index 0000000..24e71ee --- /dev/null +++ b/azext_prototype/knowledge/services/communication-services.md @@ -0,0 +1,224 @@ +--- +service_namespace: Microsoft.Communication/communicationServices +display_name: Azure Communication Services +--- + +# Azure Communication Services +> Cloud-based communication platform for adding voice, video, chat, SMS, and email capabilities to applications without managing telephony infrastructure. + +## When to Use + +- **Voice and video calling** -- embed WebRTC-based calling into web and mobile apps +- **Chat** -- real-time messaging with typing indicators, read receipts, and thread management +- **SMS** -- send and receive SMS messages programmatically (toll-free or short codes) +- **Email** -- transactional email delivery at scale with custom domains +- **Teams interop** -- connect custom apps to Microsoft Teams meetings and chats +- **Phone system** -- PSTN calling with phone number management + +Choose Communication Services over third-party APIs (Twilio, SendGrid) when you want native Azure integration, Teams interoperability, or unified billing through Azure. Choose third-party when you need broader international carrier coverage or specialized features. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Data location | United States | Data residency for communication data | +| Authentication | Managed identity + RBAC | Connection strings for quick POC start | +| Phone numbers | Not required for POC | Voice/SMS only; chat and video work without | +| Email | Optional | Requires linked Email Communication Services resource | +| Managed identity | User-assigned | For accessing ACS from backend services | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "communication" { + type = "Microsoft.Communication/communicationServices@2023-04-01" + name = var.name + location = "global" # Communication Services are global resources + parent_id = var.resource_group_id + + body = { + properties = { + dataLocation = "United States" # Data residency + } + } + + tags = var.tags + + response_export_values = ["properties.hostName", "properties.immutableResourceId"] +} +``` + +### Email Communication Services + +```hcl +resource "azapi_resource" "email" { + type = "Microsoft.Communication/emailServices@2023-04-01" + name = var.email_service_name + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + dataLocation = "United States" + } + } + + tags = var.tags +} + +# Azure-managed domain (for POC; custom domain for production) +resource "azapi_resource" "email_domain" { + type = "Microsoft.Communication/emailServices/domains@2023-04-01" + name = "AzureManagedDomain" + parent_id = azapi_resource.email.id + + body = { + location = "global" + properties = { + domainManagement = "AzureManaged" + userEngagementTracking = "Disabled" + } + } +} + +# Link email to communication services +resource "azapi_update_resource" "link_email" { + type = "Microsoft.Communication/communicationServices@2023-04-01" + resource_id = azapi_resource.communication.id + + body = { + properties = { + linkedDomains = [ + azapi_resource.email_domain.id + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# Communication Services Contributor -- full access to ACS resource +resource "azapi_resource" "acs_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.communication.id}${var.managed_identity_principal_id}acs-contributor") + parent_id = azapi_resource.communication.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Communication Services does not support private endpoints. All communication traffic is secured via TLS. Access tokens and connection strings are used for authentication. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Communication Services resource') +param name string + +@description('Data location for communication data residency') +param dataLocation string = 'United States' + +@description('Tags to apply') +param tags object = {} + +resource communication 'Microsoft.Communication/communicationServices@2023-04-01' = { + name: name + location: 'global' + tags: tags + properties: { + dataLocation: dataLocation + } +} + +output id string = communication.id +output name string = communication.name +output hostName string = communication.properties.hostName +``` + +### Email Communication Services + +```bicep +@description('Email service name') +param emailServiceName string + +resource emailService 'Microsoft.Communication/emailServices@2023-04-01' = { + name: emailServiceName + location: 'global' + properties: { + dataLocation: 'United States' + } +} + +resource emailDomain 'Microsoft.Communication/emailServices/domains@2023-04-01' = { + parent: emailService + name: 'AzureManagedDomain' + location: 'global' + properties: { + domainManagement: 'AzureManaged' + userEngagementTracking: 'Disabled' + } +} + +output emailServiceId string = emailService.id +output emailDomainId string = emailDomain.id +output mailFromSenderDomain string = emailDomain.properties.mailFromSenderDomain +``` + +### RBAC Assignment + +```bicep +@description('Principal ID for ACS management') +param principalId string + +resource acsContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(communication.id, principalId, 'contributor') + scope: communication + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c') // Contributor + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Connection string in client code | Secret exposed to end users | Use short-lived access tokens issued by your backend; never embed connection strings in frontend | +| Missing CORS configuration | Browser blocks WebRTC signaling | Configure CORS on your backend that issues tokens | +| Phone number provisioning delays | Can take days for toll-free or short codes | Start phone number acquisition early; use chat/video for initial POC | +| Email domain verification | Emails rejected without verified domain | Use Azure-managed domain for POC; verify custom domain for production | +| Token expiration | Calls/chats disconnected after token expires | Implement token refresh logic; default token lifetime is 24 hours | +| Data residency misconfiguration | Data stored in wrong region; compliance violations | Set `dataLocation` at creation time; cannot be changed later | +| Rate limits on SMS | Messages throttled or rejected | Implement retry logic with exponential backoff | +| Missing event subscription | No notifications for incoming messages/calls | Configure Event Grid subscriptions for real-time event handling | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Custom email domain | P2 | Configure and verify custom domain for branded email delivery | +| Phone number acquisition | P2 | Provision toll-free or local phone numbers for SMS and voice | +| Call recording | P3 | Enable server-side call recording with Azure Blob Storage | +| Teams interop | P2 | Configure Teams interop for joining meetings from custom apps | +| Event Grid integration | P1 | Subscribe to ACS events for incoming calls, messages, and delivery reports | +| Token management service | P1 | Build a secure backend service for issuing and refreshing access tokens | +| Call diagnostics | P3 | Enable call quality diagnostics and monitoring | +| Custom domain for chat | P3 | Configure custom domain for chat endpoint branding | +| PSTN connectivity | P2 | Set up direct routing or Azure-managed PSTN for phone calls | +| Compliance recording | P3 | Implement compliance recording for regulated industries | diff --git a/azext_prototype/knowledge/services/container-app-environment.md b/azext_prototype/knowledge/services/container-app-environment.md new file mode 100644 index 0000000..6e47bf3 --- /dev/null +++ b/azext_prototype/knowledge/services/container-app-environment.md @@ -0,0 +1,135 @@ +--- +service_namespace: Microsoft.App/managedEnvironments +display_name: Container Apps Environment +depends_on: + - Microsoft.OperationalInsights/workspaces +--- + +# Container Apps Environment + +> Shared hosting environment for Azure Container Apps that provides networking, logging, and Dapr configuration. + +## When to Use +- Required parent resource for all Container Apps +- Provides shared VNet integration, Log Analytics, and Dapr configuration +- One environment per application group (microservices that communicate) + +## POC Defaults +- **Plan**: Consumption (serverless, pay-per-use) +- **VNet integration**: Recommended (requires /23 subnet minimum) +- **Log Analytics**: Required — environment cannot be created without it + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.environment_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + appLogsConfiguration = { + destination = "log-analytics" + logAnalyticsConfiguration = { + customerId = var.log_analytics_customer_id + sharedKey = var.log_analytics_shared_key + } + } + } + } + + tags = var.tags + response_export_values = ["*"] +} +``` + +### VNet-Integrated Environment +```hcl +resource "azapi_resource" "container_app_env" { + type = "Microsoft.App/managedEnvironments@2024-03-01" + name = var.environment_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + vnetConfiguration = { + infrastructureSubnetId = var.container_apps_subnet_id + internal = false # true = internal only (no public ingress) + } + appLogsConfiguration = { + destination = "log-analytics" + logAnalyticsConfiguration = { + customerId = var.log_analytics_customer_id + sharedKey = var.log_analytics_shared_key + } + } + } + } + + tags = var.tags + response_export_values = ["*"] +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param environmentName string +param location string = resourceGroup().location +param logAnalyticsCustomerId string +@secure() +param logAnalyticsSharedKey string +param tags object = {} + +resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { + name: environmentName + location: location + properties: { + appLogsConfiguration: { + destination: 'log-analytics' + logAnalyticsConfiguration: { + customerId: logAnalyticsCustomerId + sharedKey: logAnalyticsSharedKey + } + } + } + tags: tags +} + +output environmentId string = containerAppEnv.id +output defaultDomain string = containerAppEnv.properties.defaultDomain +output staticIp string = containerAppEnv.properties.staticIp +``` + +## Common Pitfalls +- **NEVER use conditional `null` for optional ARM properties**: azapi v2 serializes Terraform `null` as JSON `null`, but ARM rejects properties set to `null` — they must be **absent** from the body. Instead of `vnetConfiguration = var.enable ? { ... } : null`, use `merge()` in locals to produce a properties map that omits the key entirely when disabled: + ```hcl + # WRONG — ARM rejects vnetConfiguration: null + vnetConfiguration = var.enable_vnet ? { ... } : null + + # CORRECT — omit the property entirely + locals { + base_properties = { + appLogsConfiguration = { ... } + } + vnet_properties = var.enable_vnet ? { + vnetConfiguration = { ... } + } : {} + environment_properties = merge(local.base_properties, local.vnet_properties) + } + ``` +- **Log Analytics required**: The environment CANNOT be created without a Log Analytics workspace. Ensure the workspace exists before creating the environment. +- **Subnet sizing**: VNet-integrated subnets must be at least /23 (512 addresses). A /27 or /28 will fail. The subnet must be delegated to `Microsoft.App/environments`. +- **Log Analytics shared key retrieval**: Use `data "azapi_resource_action"` (not `resource`) for read-only operations like fetching the shared key. Using `resource` causes re-execution on every apply. +- **Internal vs external**: Setting `internal = true` disables all public ingress to ALL apps in the environment. Individual apps cannot override this. + +## Production Backlog Items +- Dedicated workload profile plan for predictable performance and reserved capacity +- Custom VNET configuration with internal-only access and private DNS zones +- Dapr component configuration for service-to-service communication +- Zone redundancy for high availability diff --git a/azext_prototype/knowledge/services/container-apps.md b/azext_prototype/knowledge/services/container-apps.md index 0dff349..0df186e 100644 --- a/azext_prototype/knowledge/services/container-apps.md +++ b/azext_prototype/knowledge/services/container-apps.md @@ -1,485 +1,308 @@ -# Azure Container Apps - -> Serverless container platform for running microservices and containerized applications with built-in autoscaling, HTTPS ingress, and Dapr integration. - -## When to Use -- Running containerized web APIs, background processors, or event-driven microservices -- Applications that need automatic scaling (including scale to zero) -- Microservice architectures that benefit from Dapr sidecars for service-to-service communication - -## POC Defaults -- **Environment plan**: Consumption (serverless, pay-per-use) -- **Min replicas**: 0 (scale to zero for cost savings) -- **Max replicas**: 3 (sufficient for POC load) -- **Ingress**: External (public HTTPS endpoint) -- **Container Registry**: Basic SKU (lowest cost for POC) - -## Terraform Patterns - -### Basic Resource -```hcl -resource "azurerm_log_analytics_workspace" "this" { - name = "${var.project_name}-logs" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - sku = "PerGB2018" - retention_in_days = 30 - - tags = var.tags -} - -resource "azurerm_container_app_environment" "this" { - name = "${var.project_name}-env" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - log_analytics_workspace_id = azurerm_log_analytics_workspace.this.id - - tags = var.tags -} - -resource "azurerm_container_registry" "this" { - name = var.acr_name # 5-50 chars, alphanumeric only - resource_group_name = azurerm_resource_group.this.name - location = azurerm_resource_group.this.location - sku = "Basic" - admin_enabled = false # Use managed identity, not admin credentials - - tags = var.tags -} - -resource "azurerm_user_assigned_identity" "app" { - name = "${var.project_name}-app-id" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name -} - -# Grant the managed identity AcrPull on the container registry -resource "azurerm_role_assignment" "acr_pull" { - scope = azurerm_container_registry.this.id - role_definition_name = "AcrPull" - principal_id = azurerm_user_assigned_identity.app.principal_id -} - -resource "azurerm_container_app" "this" { - name = var.app_name - container_app_environment_id = azurerm_container_app_environment.this.id - resource_group_name = azurerm_resource_group.this.name - revision_mode = "Single" - - identity { - type = "UserAssigned" - identity_ids = [azurerm_user_assigned_identity.app.id] - } - - registry { - server = azurerm_container_registry.this.login_server - identity = azurerm_user_assigned_identity.app.id - } - - template { - min_replicas = 0 - max_replicas = 3 - - container { - name = var.app_name - image = "${azurerm_container_registry.this.login_server}/${var.image_name}:${var.image_tag}" - cpu = 0.5 - memory = "1Gi" - - env { - name = "AZURE_CLIENT_ID" - value = azurerm_user_assigned_identity.app.client_id - } - - liveness_probe { - transport = "HTTP" - path = "/health" - port = 8080 - } - - readiness_probe { - transport = "HTTP" - path = "/ready" - port = 8080 - } - } - } - - ingress { - external_enabled = true - target_port = 8080 - transport = "auto" - - traffic_weight { - percentage = 100 - latest_revision = true - } - } - - tags = var.tags - - depends_on = [azurerm_role_assignment.acr_pull] -} -``` - -### RBAC Assignment -```hcl -# Container Apps uses standard Azure RBAC for control-plane operations. -# For data-plane access to OTHER services, assign roles to the app's managed identity. - -# AcrPull — required for pulling images from Container Registry -# Role ID: 7f951dda-4ed3-4680-a7ca-43fe172d538d -resource "azurerm_role_assignment" "acr_pull" { - scope = azurerm_container_registry.this.id - role_definition_name = "AcrPull" - principal_id = azurerm_user_assigned_identity.app.principal_id -} - -# Example: grant access to Key Vault secrets -resource "azurerm_role_assignment" "kv_secrets_user" { - scope = azurerm_key_vault.this.id - role_definition_name = "Key Vault Secrets User" - principal_id = azurerm_user_assigned_identity.app.principal_id -} - -# Example: grant access to Storage blobs -resource "azurerm_role_assignment" "storage_blob_contributor" { - scope = azurerm_storage_account.this.id - role_definition_name = "Storage Blob Data Contributor" - principal_id = azurerm_user_assigned_identity.app.principal_id -} -``` - -### Private Endpoint -```hcl -# Container Apps does NOT use private endpoints. -# Instead, use VNet integration via the Container Apps Environment. - -resource "azurerm_container_app_environment" "this" { - name = "${var.project_name}-env" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - log_analytics_workspace_id = azurerm_log_analytics_workspace.this.id - infrastructure_subnet_id = azurerm_subnet.container_apps.id # VNet integration - internal_load_balancer_enabled = false # true = internal only - - tags = var.tags -} - -# The subnet must be delegated to Microsoft.App/environments and sized /23 or larger -resource "azurerm_subnet" "container_apps" { - name = "snet-container-apps" - resource_group_name = azurerm_resource_group.this.name - virtual_network_name = azurerm_virtual_network.this.name - address_prefixes = ["10.0.16.0/23"] # Minimum /23 for Container Apps - - delegation { - name = "container-apps" - service_delegation { - name = "Microsoft.App/environments" - actions = ["Microsoft.Network/virtualNetworks/subnets/join/action"] - } - } -} -``` - -## Bicep Patterns - -### Basic Resource -```bicep -param projectName string -param location string = resourceGroup().location -param appName string -param acrName string -param imageName string -param imageTag string = 'latest' -param tags object = {} - -resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = { - name: '${projectName}-logs' - location: location - properties: { - sku: { - name: 'PerGB2018' - } - retentionInDays: 30 - } - tags: tags -} - -resource containerAppEnv 'Microsoft.App/managedEnvironments@2024-03-01' = { - name: '${projectName}-env' - location: location - properties: { - appLogsConfiguration: { - destination: 'log-analytics' - logAnalyticsConfiguration: { - customerId: logAnalytics.properties.customerId - sharedKey: logAnalytics.listKeys().primarySharedKey - } - } - } - tags: tags -} - -resource acr 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = { - name: acrName - location: location - sku: { - name: 'Basic' - } - properties: { - adminUserEnabled: false - } - tags: tags -} - -resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' = { - name: '${projectName}-app-id' - location: location -} - -// AcrPull role assignment -var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d' -resource acrPullRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(acr.id, identity.id, acrPullRoleId) - scope: acr - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId) - principalId: identity.properties.principalId - principalType: 'ServicePrincipal' - } -} - -resource containerApp 'Microsoft.App/containerApps@2024-03-01' = { - name: appName - location: location - identity: { - type: 'UserAssigned' - userAssignedIdentities: { - '${identity.id}': {} - } - } - properties: { - managedEnvironmentId: containerAppEnv.id - configuration: { - registries: [ - { - server: acr.properties.loginServer - identity: identity.id - } - ] - ingress: { - external: true - targetPort: 8080 - transport: 'auto' - traffic: [ - { - weight: 100 - latestRevision: true - } - ] - } - } - template: { - containers: [ - { - name: appName - image: '${acr.properties.loginServer}/${imageName}:${imageTag}' - resources: { - cpu: json('0.5') - memory: '1Gi' - } - env: [ - { - name: 'AZURE_CLIENT_ID' - value: identity.properties.clientId - } - ] - probes: [ - { - type: 'Liveness' - httpGet: { - path: '/health' - port: 8080 - } - } - { - type: 'Readiness' - httpGet: { - path: '/ready' - port: 8080 - } - } - ] - } - ] - scale: { - minReplicas: 0 - maxReplicas: 3 - } - } - } - tags: tags - dependsOn: [ - acrPullRole - ] -} - -output fqdn string = containerApp.properties.configuration.ingress.fqdn -output appUrl string = 'https://${containerApp.properties.configuration.ingress.fqdn}' -``` - -### RBAC Assignment -```bicep -// Container Apps uses standard Azure RBAC. -// Assign roles to the app's managed identity for access to other services. - -param principalId string - -// Example: Key Vault Secrets User -var kvSecretsUserRoleId = '4633458b-17de-408a-b874-0445c86b69e6' - -resource kvSecretsRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(keyVault.id, principalId, kvSecretsUserRoleId) - scope: keyVault - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', kvSecretsUserRoleId) - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python -```python -# The application runs INSIDE the container. -# Use DefaultAzureCredential with the user-assigned managed identity. - -from azure.identity import DefaultAzureCredential -import os - -# AZURE_CLIENT_ID is set as an environment variable on the container -credential = DefaultAzureCredential( - managed_identity_client_id=os.environ.get("AZURE_CLIENT_ID") -) - -# Use this credential with any Azure SDK client. -# Example with Key Vault: -from azure.keyvault.secrets import SecretClient -secret_client = SecretClient( - vault_url="https://.vault.azure.net/", - credential=credential -) - -# Example health endpoint (Flask) -from flask import Flask -app = Flask(__name__) - -@app.route("/health") -def health(): - return {"status": "healthy"}, 200 - -@app.route("/ready") -def ready(): - return {"status": "ready"}, 200 - -if __name__ == "__main__": - app.run(host="0.0.0.0", port=8080) -``` - -### C# -```csharp -// The application runs INSIDE the container. -// Use DefaultAzureCredential with the user-assigned managed identity. - -using Azure.Identity; - -var builder = WebApplication.CreateBuilder(args); - -// Configure managed identity credential -var clientId = builder.Configuration["AZURE_CLIENT_ID"]; -var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions -{ - ManagedIdentityClientId = clientId -}); - -// Register credential for DI -builder.Services.AddSingleton(credential); - -// Example: register Key Vault client -builder.Services.AddSingleton(sp => -{ - var cred = sp.GetRequiredService(); - return new Azure.Security.KeyVault.Secrets.SecretClient( - new Uri("https://.vault.azure.net/"), cred); -}); - -var app = builder.Build(); - -// Health probes -app.MapGet("/health", () => Results.Ok(new { status = "healthy" })); -app.MapGet("/ready", () => Results.Ok(new { status = "ready" })); - -app.Run(); -``` - -### Node.js -```typescript -// The application runs INSIDE the container. -// Use DefaultAzureCredential with the user-assigned managed identity. - -import { DefaultAzureCredential } from "@azure/identity"; -import { SecretClient } from "@azure/keyvault-secrets"; -import express from "express"; - -const credential = new DefaultAzureCredential({ - managedIdentityClientId: process.env.AZURE_CLIENT_ID, -}); - -// Example: Key Vault client -const secretClient = new SecretClient( - "https://.vault.azure.net/", - credential -); - -const app = express(); - -// Health probes -app.get("/health", (req, res) => { - res.json({ status: "healthy" }); -}); - -app.get("/ready", (req, res) => { - res.json({ status: "ready" }); -}); - -app.listen(8080, "0.0.0.0", () => { - console.log("Server running on port 8080"); -}); -``` - -## Common Pitfalls -- **No private endpoints**: Container Apps does NOT support private endpoints. Network isolation is achieved through VNet integration on the Container Apps Environment. Set `internal_load_balancer_enabled = true` for internal-only access. -- **Subnet sizing**: The VNet-integrated subnet must be at least /23 (512 addresses). A /27 or /28 will fail. The subnet must be delegated to `Microsoft.App/environments`. -- **AcrPull role timing**: The role assignment must propagate before the container app tries to pull the image. Use `depends_on` to ensure ordering. Propagation can take up to 10 minutes. -- **Admin credentials on ACR**: Never set `admin_enabled = true`. Use managed identity with AcrPull role instead. -- **Missing health probes**: Without liveness and readiness probes, Container Apps cannot properly manage rolling deployments and traffic routing. -- **Secrets via environment variables**: Do not put secrets directly in environment variables. Use Key Vault references with the managed identity, or use Container Apps' built-in secrets store that pulls from Key Vault. -- **Scale-to-zero cold start**: When min replicas is 0, the first request after scale-down triggers a cold start (container pull + startup). Set `min_replicas = 1` if latency is critical. -- **CPU/memory constraints**: Consumption plan allows max 4 vCPUs and 8 GiB memory per container. Dedicated plan required for larger workloads. -- **Log Analytics required**: The Container Apps Environment requires a Log Analytics workspace. You cannot create the environment without one. - -## Production Backlog Items -- Custom domain with managed TLS certificate -- VNet integration with internal-only ingress for private workloads -- Dapr sidecar configuration for service-to-service communication -- Dedicated workload profile plan (instead of Consumption) for predictable performance -- Horizontal scaling rules based on HTTP concurrency, KEDA scalers, or custom metrics -- Revision management with traffic splitting for blue/green deployments -- Volume mounts for persistent storage (Azure Files) -- Init containers for startup dependencies -- Managed certificate with custom domain and DNS validation -- Integration with Azure Front Door or Application Gateway for WAF +--- +service_namespace: Microsoft.App/containerApps +display_name: Azure Container Apps +depends_on: + - Microsoft.App/managedEnvironments + - Microsoft.ContainerRegistry/registries + - Microsoft.ManagedIdentity/userAssignedIdentities +--- + +# Azure Container Apps + +> Serverless container platform for running microservices and containerized applications with built-in autoscaling, HTTPS ingress, and Dapr integration. + +## When to Use +- Running containerized web APIs, background processors, or event-driven microservices +- Applications that need automatic scaling (including scale to zero) +- Microservice architectures that benefit from Dapr sidecars + +## POC Defaults +- **Min replicas**: 0 (scale to zero for cost savings) +- **Max replicas**: 3 (sufficient for POC load) +- **Ingress**: External (public HTTPS endpoint) +- **CPU**: 0.5 vCPU per container +- **Memory**: 1 GiB per container +- **Identity**: UserAssigned managed identity (required for ACR pull) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "container_app" { + type = "Microsoft.App/containerApps@2024-03-01" + name = var.app_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + properties = { + managedEnvironmentId = var.container_app_environment_id + configuration = { + registries = [ + { + server = var.acr_login_server + identity = var.managed_identity_id + } + ] + ingress = { + external = true + targetPort = 8080 + transport = "auto" + traffic = [ + { + weight = 100 + latestRevision = true + } + ] + } + } + template = { + containers = [ + { + name = var.app_name + image = "${var.acr_login_server}/${var.image_name}:${var.image_tag}" + resources = { + cpu = 0.5 + memory = "1Gi" + } + env = [ + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + }, + { + name = "APPLICATIONINSIGHTS_CONNECTION_STRING" + value = var.app_insights_connection_string + } + ] + probes = [ + { + type = "Liveness" + httpGet = { + path = "/health" + port = 8080 + } + }, + { + type = "Readiness" + httpGet = { + path = "/ready" + port = 8080 + } + } + ] + } + ] + scale = { + minReplicas = 0 + maxReplicas = 3 + } + } + } + } + + tags = var.tags + response_export_values = ["properties.configuration.ingress.fqdn"] +} +``` + +### RBAC Assignments (for app identity to access other services) +```hcl +# AcrPull — required for pulling images from Container Registry +resource "azapi_resource" "acr_pull" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${var.acr_id}-${var.principal_id}-7f951dda") + parent_id = var.acr_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} + +# Key Vault Secrets User — for reading secrets +resource "azapi_resource" "kv_secrets_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${var.key_vault_id}-${var.principal_id}-4633458b") + parent_id = var.key_vault_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### KEDA Scaler Configuration +```hcl +# Service Bus KEDA scaler — identity is a SIBLING of type and metadata +scale = { + minReplicas = 0 + maxReplicas = 10 + rules = [ + { + name = "servicebus-rule" + custom = { + type = "azure-servicebus" + metadata = { + namespace = var.servicebus_namespace_name # short name, NOT FQDN + queueName = var.servicebus_queue_name + messageCount = "5" + } + identity = var.managed_identity_id # UAMI resource ID + } + } + ] +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param appName string +param location string = resourceGroup().location +param environmentId string +param acrLoginServer string +param imageName string +param imageTag string +param identityId string +param identityClientId string +param tags object = {} + +resource containerApp 'Microsoft.App/containerApps@2024-03-01' = { + name: appName + location: location + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${identityId}': {} + } + } + properties: { + managedEnvironmentId: environmentId + configuration: { + registries: [ + { + server: acrLoginServer + identity: identityId + } + ] + ingress: { + external: true + targetPort: 8080 + transport: 'auto' + traffic: [{ weight: 100, latestRevision: true }] + } + } + template: { + containers: [ + { + name: appName + image: '${acrLoginServer}/${imageName}:${imageTag}' + resources: { cpu: json('0.5'), memory: '1Gi' } + env: [ + { name: 'AZURE_CLIENT_ID', value: identityClientId } + ] + probes: [ + { type: 'Liveness', httpGet: { path: '/health', port: 8080 } } + { type: 'Readiness', httpGet: { path: '/ready', port: 8080 } } + ] + } + ] + scale: { minReplicas: 0, maxReplicas: 3 } + } + } + tags: tags +} + +output fqdn string = containerApp.properties.configuration.ingress.fqdn +output appUrl string = 'https://${containerApp.properties.configuration.ingress.fqdn}' +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +import os + +# AZURE_CLIENT_ID env var set on the container for UAMI disambiguation +credential = DefaultAzureCredential( + managed_identity_client_id=os.environ.get("AZURE_CLIENT_ID") +) + +# Use with any Azure SDK client (Key Vault, Storage, Service Bus, etc.) +from azure.keyvault.secrets import SecretClient +secret_client = SecretClient( + vault_url="https://.vault.azure.net/", + credential=credential +) +``` + +### C# +```csharp +using Azure.Identity; + +var builder = WebApplication.CreateBuilder(args); + +var clientId = builder.Configuration["AZURE_CLIENT_ID"]; +var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions +{ + ManagedIdentityClientId = clientId +}); + +builder.Services.AddSingleton(credential); + +var app = builder.Build(); +app.MapGet("/health", () => Results.Ok(new { status = "healthy" })); +app.MapGet("/ready", () => Results.Ok(new { status = "ready" })); +app.Run(); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import express from "express"; + +const credential = new DefaultAzureCredential({ + managedIdentityClientId: process.env.AZURE_CLIENT_ID, +}); + +const app = express(); +app.get("/health", (req, res) => res.json({ status: "healthy" })); +app.get("/ready", (req, res) => res.json({ status: "ready" })); +app.listen(8080, "0.0.0.0"); +``` + +## Common Pitfalls +- **No private endpoints**: Container Apps does NOT support private endpoints. Network isolation is via VNet integration on the Container Apps Environment (`internal = true`). +- **AcrPull role timing**: The RBAC assignment must propagate before the container app pulls the image. Propagation can take up to 10 minutes. Use `depends_on` to ensure ordering. +- **SystemAssigned-only identity fails on first deploy**: Use UserAssigned (or SystemAssigned,UserAssigned) for ACR pull. SystemAssigned alone doesn't exist until after the resource is created, causing the initial image pull to fail. +- **Missing health probes**: Without liveness and readiness probes, Container Apps cannot properly manage rolling deployments. +- **Secrets in plain env vars**: Do not put secrets in environment variables. Use Key Vault references with managed identity. +- **Scale-to-zero cold start**: First request after scale-down triggers container pull + startup (30-60s). Set `minReplicas = 1` if latency is critical. +- **KEDA scaler identity**: The `identity` field is a sibling of `type` and `metadata`. Do NOT put `clientId` in `metadata`. +- **Service Bus KEDA namespace**: Use the short namespace name, NOT the FQDN. +- **Duplicate RBAC**: Do NOT re-create RBAC assignments already created in upstream service stages (causes ARM 409 Conflict). +- **ACR image reference**: Use upstream stage output for ACR login server, NEVER hardcode. + +## Production Backlog Items +- Custom domain with managed TLS certificate +- Revision management with traffic splitting for blue/green deployments +- Dapr sidecar configuration for service-to-service communication +- Horizontal scaling rules based on HTTP concurrency or custom metrics +- Volume mounts for persistent storage (Azure Files) +- Init containers for startup dependencies +- Integration with Azure Front Door or Application Gateway for WAF diff --git a/azext_prototype/knowledge/services/container-instances.md b/azext_prototype/knowledge/services/container-instances.md new file mode 100644 index 0000000..ff0dc6b --- /dev/null +++ b/azext_prototype/knowledge/services/container-instances.md @@ -0,0 +1,309 @@ +--- +service_namespace: Microsoft.ContainerInstance/containerGroups +display_name: Azure Container Instances +--- + +# Azure Container Instances +> Serverless container platform for running isolated containers on demand without managing VMs or orchestrators, ideal for burst workloads, batch jobs, and simple container deployments. + +## When to Use + +- **Quick container deployment** -- run a container image without provisioning VMs or Kubernetes clusters +- **Batch processing** -- short-lived jobs that process data and exit (ETL, data migration, report generation) +- **CI/CD build agents** -- ephemeral build/test runners +- **Sidecar containers** -- multi-container groups for init containers, log shippers, or proxies +- **Dev/test environments** -- quick spin-up of containerized applications for testing +- **Event-driven containers** -- trigger container execution from Logic Apps, Functions, or Event Grid + +Prefer Container Instances over Container Apps when you need simple, short-lived container execution without scaling, ingress routing, or Dapr integration. Use Container Apps for long-running microservices with auto-scaling. Use AKS for complex multi-service orchestration. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| OS type | Linux | Default; Windows available for .NET Framework | +| CPU | 1 core | Sufficient for most POC workloads | +| Memory | 1.5 GiB | Default allocation | +| Restart policy | OnFailure | Restart only on failure; use "Never" for batch jobs | +| IP address type | Public | Flag private (VNet) deployment as production backlog item | +| Image source | ACR with managed identity | No admin credentials needed | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "container_group" { + type = "Microsoft.ContainerInstance/containerGroups@2023-05-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + properties = { + osType = "Linux" + restartPolicy = "OnFailure" + ipAddress = { + type = "Public" + ports = [ + { + protocol = "TCP" + port = 80 + } + ] + } + imageRegistryCredentials = [ + { + server = var.acr_login_server + identity = var.managed_identity_id + } + ] + containers = [ + { + name = var.container_name + properties = { + image = "${var.acr_login_server}/${var.image_name}:${var.image_tag}" + resources = { + requests = { + cpu = 1 + memoryInGB = 1.5 + } + } + ports = [ + { + protocol = "TCP" + port = 80 + } + ] + environmentVariables = [ + { + name = "AZURE_CLIENT_ID" + value = var.managed_identity_client_id + } + ] + } + } + ] + } + } + + tags = var.tags + + response_export_values = ["properties.ipAddress.ip", "properties.ipAddress.fqdn"] +} +``` + +### Multi-Container Group (Sidecar Pattern) + +```hcl +resource "azapi_resource" "container_group_sidecar" { + type = "Microsoft.ContainerInstance/containerGroups@2023-05-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + osType = "Linux" + restartPolicy = "Always" + containers = [ + { + name = "app" + properties = { + image = "${var.acr_login_server}/${var.app_image}:latest" + resources = { + requests = { + cpu = 1 + memoryInGB = 1 + } + } + ports = [ + { + protocol = "TCP" + port = 80 + } + ] + } + }, + { + name = "log-shipper" + properties = { + image = "${var.acr_login_server}/${var.sidecar_image}:latest" + resources = { + requests = { + cpu = 0.5 + memoryInGB = 0.5 + } + } + } + } + ] + ipAddress = { + type = "Public" + ports = [ + { + protocol = "TCP" + port = 80 + } + ] + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# ACI's managed identity accessing ACR for image pull +resource "azapi_resource" "acr_pull_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.acr_id}${var.managed_identity_principal_id}acr-pull") + parent_id = var.acr_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" # AcrPull + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the container group') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Container image (including registry)') +param image string + +@description('ACR login server') +param acrLoginServer string + +@description('Managed identity resource ID') +param managedIdentityId string + +@description('Managed identity client ID') +param managedIdentityClientId string + +@description('Tags to apply') +param tags object = {} + +resource containerGroup 'Microsoft.ContainerInstance/containerGroups@2023-05-01' = { + name: name + location: location + tags: tags + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + properties: { + osType: 'Linux' + restartPolicy: 'OnFailure' + imageRegistryCredentials: [ + { + server: acrLoginServer + identity: managedIdentityId + } + ] + containers: [ + { + name: 'main' + properties: { + image: image + resources: { + requests: { + cpu: 1 + memoryInGB: json('1.5') + } + } + ports: [ + { + protocol: 'TCP' + port: 80 + } + ] + environmentVariables: [ + { + name: 'AZURE_CLIENT_ID' + value: managedIdentityClientId + } + ] + } + } + ] + ipAddress: { + type: 'Public' + ports: [ + { + protocol: 'TCP' + port: 80 + } + ] + } + } +} + +output id string = containerGroup.id +output name string = containerGroup.name +output ipAddress string = containerGroup.properties.ipAddress.ip +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity') +param principalId string + +// AcrPull -- allow container group to pull images from ACR +resource acrPullRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(acr.id, principalId, '7f951dda-4ed3-4680-a7ca-43fe172d538d') + scope: acr + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7f951dda-4ed3-4680-a7ca-43fe172d538d') // AcrPull + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Using admin credentials for ACR | Secrets in config, rotation burden | Use managed identity with AcrPull role and `imageRegistryCredentials.identity` | +| Container group immutability | Cannot update containers in-place; must delete and recreate | Design for immutable deployments; use deployment scripts or CI/CD | +| No auto-scaling | ACI does not scale horizontally; fixed resource allocation | Use Container Apps for auto-scaling scenarios | +| Public IP without authentication | Container exposed to internet without auth | Add application-level authentication or use VNet deployment | +| Exceeding resource limits | Max 4 CPU, 16 GiB memory per container group | Split into multiple container groups or use AKS for larger workloads | +| Restart policy mismatch | `Always` for batch jobs wastes resources; `Never` for services loses availability | Use `OnFailure` for services, `Never` for batch jobs | +| Forgetting port alignment | IP address ports must match container ports | Ensure `ipAddress.ports` and `containers[].ports` are consistent | + +## Production Backlog Items + +- [ ] Deploy into VNet subnet for private networking +- [ ] Configure diagnostic logging to Log Analytics workspace +- [ ] Set up monitoring alerts (CPU usage, memory usage, restart count) +- [ ] Move to Container Apps or AKS for production auto-scaling and ingress management +- [ ] Configure liveness and readiness probes +- [ ] Review CPU and memory allocations based on actual usage +- [ ] Implement secure environment variables (use `secureValue` for secrets) +- [ ] Set up Azure Monitor container insights +- [ ] Consider GPU-enabled container groups for ML inference workloads diff --git a/azext_prototype/knowledge/services/container-registry.md b/azext_prototype/knowledge/services/container-registry.md index d6b6e18..fceaef2 100644 --- a/azext_prototype/knowledge/services/container-registry.md +++ b/azext_prototype/knowledge/services/container-registry.md @@ -1,249 +1,312 @@ -# Azure Container Registry -> Managed Docker container registry for storing, managing, and serving container images and OCI artifacts. - -## When to Use - -- **Container image hosting** -- store and serve Docker images for Container Apps, App Service, Functions, and Kubernetes -- **CI/CD artifact storage** -- push images from build pipelines, pull from deployment targets -- **Helm chart registry** -- store and distribute Helm charts as OCI artifacts -- **Supply chain security** -- image signing, vulnerability scanning, content trust - -Container Registry is a foundational infrastructure service. Any architecture using containers (Container Apps, Azure Functions with custom containers, AKS) requires a registry. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | Basic | Lowest cost; 10 GiB storage | -| SKU (with geo-replication) | Standard | 100 GiB storage, webhooks | -| Admin user | Disabled | Always use managed identity with AcrPull role | -| Public network access | Enabled (POC) | Flag private endpoint as production backlog item | -| Anonymous pull | Disabled | Require authentication for all image pulls | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_container_registry" "this" { - name = var.name # Must be globally unique, alphanumeric only - location = var.location - resource_group_name = var.resource_group_name - sku = "Basic" - admin_enabled = false # CRITICAL: Never enable admin user - public_network_access_enabled = true # Set false when using private endpoint - - tags = var.tags -} -``` - -### RBAC Assignment - -```hcl -# AcrPull -- allows container runtimes to pull images -resource "azurerm_role_assignment" "acr_pull" { - scope = azurerm_container_registry.this.id - role_definition_name = "AcrPull" - principal_id = var.managed_identity_principal_id -} - -# AcrPush -- allows CI/CD pipelines to push images -resource "azurerm_role_assignment" "acr_push" { - scope = azurerm_container_registry.this.id - role_definition_name = "AcrPush" - principal_id = var.ci_identity_principal_id -} -``` - -RBAC role IDs: -- AcrPull: `7f951dda-4ed3-4680-a7ca-43fe172d538d` -- AcrPush: `8311e382-0749-4cb8-b61a-304f252e45ec` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "acr" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_container_registry.this.id - subresource_names = ["registry"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.azurecr.io` - -**Note:** Private endpoints require Premium tier. For POC with Basic/Standard tier, use IP firewall rules or public access. - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the container registry (globally unique, alphanumeric only)') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Tags to apply') -param tags object = {} - -resource acr 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = { - name: name - location: location - tags: tags - sku: { - name: 'Basic' - } - properties: { - adminUserEnabled: false // CRITICAL: Never enable admin user - publicNetworkAccess: 'Enabled' // Set 'Disabled' when using private endpoint - } -} - -output id string = acr.id -output name string = acr.name -output loginServer string = acr.properties.loginServer -``` - -### RBAC Assignment - -```bicep -@description('Principal ID of the managed identity for image pulling') -param pullPrincipalId string - -// AcrPull role -var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d' - -resource acrPullAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(acr.id, pullPrincipalId, acrPullRoleId) - scope: acr - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId) - principalId: pullPrincipalId - principalType: 'ServicePrincipal' - } -} -``` - -### Private Endpoint - -```bicep -@description('Subnet ID for private endpoint') -param subnetId string = '' - -@description('Private DNS zone ID for ACR') -param privateDnsZoneId string = '' - -resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { - name: 'pe-${name}' - location: location - tags: tags - properties: { - subnet: { - id: subnetId - } - privateLinkServiceConnections: [ - { - name: 'psc-${name}' - properties: { - privateLinkServiceId: acr.id - groupIds: ['registry'] - } - } - ] - } -} - -resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = if (!empty(subnetId) && !empty(privateDnsZoneId)) { - parent: privateEndpoint - name: 'dns-zone-group' - properties: { - privateDnsZoneConfigs: [ - { - name: 'config' - properties: { - privateDnsZoneId: privateDnsZoneId - } - } - ] - } -} -``` - -Private DNS zone: `privatelink.azurecr.io` - -**Note:** Private endpoints require Premium tier. For POC with Basic/Standard tier, use IP firewall rules or public access. - -## Application Code - -No application code patterns -- Azure Container Registry is a pure infrastructure service. Interaction happens via: - -- **Docker CLI**: `docker push`, `docker pull` (with `az acr login` for AAD auth) -- **Azure CLI**: `az acr build` for cloud builds, `az acr login` for authentication -- **CI/CD pipelines**: Push images during build, pull during deployment - -### Docker Authentication with Managed Identity - -```bash -# Local development (uses Azure CLI credential) -az acr login --name myregistry - -# CI/CD pipeline (uses service principal or managed identity) -az acr login --name myregistry --expose-token -``` - -### Container Apps Integration - -Container Apps pull images using the managed identity assigned to the Container App with `AcrPull` role. No explicit login is needed -- configure the registry in the Container App environment: - -```hcl -# Terraform: Container App referencing ACR -resource "azurerm_container_app" "this" { - # ... - registry { - server = azurerm_container_registry.this.login_server - identity = azurerm_user_assigned_identity.this.id - } -} -``` - -## Common Pitfalls - -1. **Enabling admin user** -- Admin credentials are shared secrets and violate governance policies. Always use managed identity with `AcrPull` role instead. -2. **Registry name constraints** -- Must be globally unique, 5-50 characters, alphanumeric only (no hyphens or underscores). Use the naming strategy to generate valid names. -3. **SKU limitations for private endpoints** -- Private endpoints require Premium tier. Basic and Standard tiers only support IP firewall rules. -4. **Forgetting AcrPull role for container runtimes** -- Container Apps, App Service, and Functions need the `AcrPull` role on the registry to pull images. Without it, deployments fail with authentication errors. -5. **Image tag mutability** -- By default, tags are mutable (`:latest` can be overwritten). For supply chain security, use immutable tags or content trust. -6. **Storage limits by tier** -- Basic: 10 GiB, Standard: 100 GiB, Premium: 500 GiB. Monitor storage usage and clean up untagged manifests. - -## Production Backlog Items - -- [ ] Upgrade to Premium tier for private endpoints and geo-replication -- [ ] Enable private endpoint and disable public network access -- [ ] Configure geo-replication for multi-region availability -- [ ] Enable content trust for image signing -- [ ] Enable vulnerability scanning with Microsoft Defender for Containers -- [ ] Configure retention policies for untagged manifests -- [ ] Set up webhook notifications for image push/delete events -- [ ] Implement image quarantine workflow (push, scan, approve, release) -- [ ] Configure repository-scoped tokens for granular access control +--- +service_namespace: Microsoft.ContainerRegistry/registries +display_name: Azure Container Registry +--- + +# Azure Container Registry +> Managed Docker container registry for storing, managing, and serving container images and OCI artifacts. + +## When to Use + +- **Container image hosting** -- store and serve Docker images for Container Apps, App Service, Functions, and Kubernetes +- **CI/CD artifact storage** -- push images from build pipelines, pull from deployment targets +- **Helm chart registry** -- store and distribute Helm charts as OCI artifacts +- **Supply chain security** -- image signing, vulnerability scanning, content trust + +Container Registry is a foundational infrastructure service. Any architecture using containers (Container Apps, Azure Functions with custom containers, AKS) requires a registry. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | Lowest cost; 10 GiB storage | +| SKU (with geo-replication) | Standard | 100 GiB storage, webhooks | +| Admin user | Disabled | Always use managed identity with AcrPull role | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | +| Anonymous pull | Disabled | Require authentication for all image pulls | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "acr" { + type = "Microsoft.ContainerRegistry/registries@2023-11-01-preview" + name = var.name # Must be globally unique, alphanumeric only + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + sku = { + name = "Basic" + } + properties = { + adminUserEnabled = false # CRITICAL: Never enable admin user + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + } + } + + tags = var.tags + + response_export_values = ["properties.loginServer"] +} +``` + +### RBAC Assignment + +```hcl +# AcrPull -- allows container runtimes to pull images +resource "azapi_resource" "acr_pull" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${azapi_resource.acr.id}-${var.managed_identity_principal_id}-7f951dda-4ed3-4680-a7ca-43fe172d538d") + parent_id = azapi_resource.acr.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/7f951dda-4ed3-4680-a7ca-43fe172d538d" # AcrPull + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# AcrPush -- allows CI/CD pipelines to push images +resource "azapi_resource" "acr_push" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${azapi_resource.acr.id}-${var.ci_identity_principal_id}-8311e382-0749-4cb8-b61a-304f252e45ec") + parent_id = azapi_resource.acr.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/8311e382-0749-4cb8-b61a-304f252e45ec" # AcrPush + principalId = var.ci_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +RBAC role IDs: +- AcrPull: `7f951dda-4ed3-4680-a7ca-43fe172d538d` +- AcrPush: `8311e382-0749-4cb8-b61a-304f252e45ec` + +### Private Endpoint + +```hcl +resource "azapi_resource" "acr_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.acr.id + groupIds = ["registry"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "acr_pe_dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.acr_private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.azurecr.io` + +**Note:** Private endpoints require Premium tier. For POC with Basic/Standard tier, use IP firewall rules or public access. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the container registry (globally unique, alphanumeric only)') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource acr 'Microsoft.ContainerRegistry/registries@2023-11-01-preview' = { + name: name + location: location + tags: tags + sku: { + name: 'Basic' + } + properties: { + adminUserEnabled: false // CRITICAL: Never enable admin user + publicNetworkAccess: 'Disabled' // Unless told otherwise, disabled per governance policy + } +} + +output id string = acr.id +output name string = acr.name +output loginServer string = acr.properties.loginServer +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity for image pulling') +param pullPrincipalId string + +// AcrPull role +var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d' + +resource acrPullAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(acr.id, pullPrincipalId, acrPullRoleId) + scope: acr + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId) + principalId: pullPrincipalId + principalType: 'ServicePrincipal' + } +} +``` + +### Private Endpoint + +```bicep +@description('Subnet ID for private endpoint') +param subnetId string = '' + +@description('Private DNS zone ID for ACR') +param privateDnsZoneId string = '' + +resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { + name: 'pe-${name}' + location: location + tags: tags + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'psc-${name}' + properties: { + privateLinkServiceId: acr.id + groupIds: ['registry'] + } + } + ] + } +} + +resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = if (!empty(subnetId) && !empty(privateDnsZoneId)) { + parent: privateEndpoint + name: 'dns-zone-group' + properties: { + privateDnsZoneConfigs: [ + { + name: 'config' + properties: { + privateDnsZoneId: privateDnsZoneId + } + } + ] + } +} +``` + +Private DNS zone: `privatelink.azurecr.io` + +**Note:** Private endpoints require Premium tier. For POC with Basic/Standard tier, use IP firewall rules or public access. + +## Application Code + +No application code patterns -- Azure Container Registry is a pure infrastructure service. Interaction happens via: + +- **Docker CLI**: `docker push`, `docker pull` (with `az acr login` for AAD auth) +- **Azure CLI**: `az acr build` for cloud builds, `az acr login` for authentication +- **CI/CD pipelines**: Push images during build, pull during deployment + +### Docker Authentication with Managed Identity + +```bash +# Local development (uses Azure CLI credential) +az acr login --name myregistry + +# CI/CD pipeline (uses service principal or managed identity) +az acr login --name myregistry --expose-token +``` + +### Container Apps Integration + +Container Apps pull images using the managed identity assigned to the Container App with `AcrPull` role. No explicit login is needed -- configure the registry in the Container App environment: + +```hcl +# Terraform (azapi): Container App referencing ACR via registries in configuration +resource "azapi_resource" "container_app" { + # ... + body = { + properties = { + configuration = { + registries = [ + { + server = azapi_resource.acr.output.properties.loginServer + identity = azapi_resource.user_assigned_identity.id + } + ] + } + # ... + } + } +} +``` + +## Common Pitfalls + +1. **Enabling admin user** -- Admin credentials are shared secrets and violate governance policies. Always use managed identity with `AcrPull` role instead. +2. **Registry name constraints** -- Must be globally unique, 5-50 characters, alphanumeric only (no hyphens or underscores). Use the naming strategy to generate valid names. +3. **SKU limitations for private endpoints** -- Private endpoints require Premium tier. Basic and Standard tiers only support IP firewall rules. +4. **Forgetting AcrPull role for container runtimes** -- Container Apps, App Service, and Functions need the `AcrPull` role on the registry to pull images. Without it, deployments fail with authentication errors. +5. **Image tag mutability** -- By default, tags are mutable (`:latest` can be overwritten). For supply chain security, use immutable tags or content trust. +6. **Storage limits by tier** -- Basic: 10 GiB, Standard: 100 GiB, Premium: 500 GiB. Monitor storage usage and clean up untagged manifests. + +## Production Backlog Items + +- [ ] Upgrade to Premium tier for private endpoints and geo-replication +- [ ] Enable private endpoint and disable public network access +- [ ] Configure geo-replication for multi-region availability +- [ ] Enable content trust for image signing +- [ ] Enable vulnerability scanning with Microsoft Defender for Containers +- [ ] Configure retention policies for untagged manifests +- [ ] Set up webhook notifications for image push/delete events +- [ ] Implement image quarantine workflow (push, scan, approve, release) +- [ ] Configure repository-scoped tokens for granular access control diff --git a/azext_prototype/knowledge/services/cosmos-db-sql-container.md b/azext_prototype/knowledge/services/cosmos-db-sql-container.md new file mode 100644 index 0000000..df49153 --- /dev/null +++ b/azext_prototype/knowledge/services/cosmos-db-sql-container.md @@ -0,0 +1,143 @@ +--- +service_namespace: Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers +display_name: Cosmos DB SQL Container +depends_on: + - Microsoft.DocumentDB/databaseAccounts/sqlDatabases +--- + +# Cosmos DB SQL Container + +> A schema-free JSON container within a Cosmos DB SQL database. The fundamental unit of scalability — partition key design determines performance and cost. + +## When to Use +- Every Cosmos DB application stores data in containers +- Each container has a partition key that determines data distribution +- Use separate containers for different data access patterns + +## POC Defaults +- **Partition key**: Choose based on the most common query filter (e.g., `/tenantId`, `/userId`) +- **Indexing**: Default (automatic indexing of all properties) +- **TTL**: Not enabled unless data has a natural expiry + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "cosmos_container" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15" + name = var.container_name + parent_id = azapi_resource.cosmos_database.id + + body = { + properties = { + resource = { + id = var.container_name + partitionKey = { + paths = [var.partition_key_path] + kind = "Hash" + version = 2 + } + } + } + } + + response_export_values = ["*"] +} +``` + +### RBAC Assignment +```hcl +# Data-plane access to containers is granted at the database account level +# via Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments. +# See the sqlRoleAssignments knowledge file. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param containerName string +param partitionKeyPath string + +resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2024-05-15' = { + parent: cosmosDatabase + name: containerName + properties: { + resource: { + id: containerName + partitionKey: { + paths: [partitionKeyPath] + kind: 'Hash' + version: 2 + } + } + } +} + +output containerId string = container.id +output containerName string = container.name +``` + +## Application Code + +### Python +```python +database = client.get_database_client(database_name) +container = database.get_container_client(container_name) + +# Create item +container.create_item(body={"id": "1", "name": "example", "partitionKey": "tenant1"}) + +# Query items +items = container.query_items( + query="SELECT * FROM c WHERE c.partitionKey = @pk", + parameters=[{"name": "@pk", "value": "tenant1"}], + partition_key="tenant1" +) +``` + +### C# +```csharp +var container = database.GetContainer(containerName); + +// Create item +await container.CreateItemAsync(new { id = "1", name = "example", partitionKey = "tenant1" }); + +// Query items +var query = new QueryDefinition("SELECT * FROM c WHERE c.partitionKey = @pk") + .WithParameter("@pk", "tenant1"); +using var iterator = container.GetItemQueryIterator(query, requestOptions: new QueryRequestOptions +{ + PartitionKey = new PartitionKey("tenant1") +}); +``` + +### Node.js +```typescript +const container = database.container(containerName); + +// Create item +await container.items.create({ id: "1", name: "example", partitionKey: "tenant1" }); + +// Query items +const { resources } = await container.items + .query({ + query: "SELECT * FROM c WHERE c.partitionKey = @pk", + parameters: [{ name: "@pk", value: "tenant1" }], + }) + .fetchAll(); +``` + +## Common Pitfalls +- **Partition key is immutable**: Once set, the partition key path cannot be changed. Choose carefully based on query patterns. +- **Cross-partition queries are expensive**: Queries without the partition key filter fan out to all partitions. Always include the partition key in queries. +- **Partition key version**: Use version 2 (supports large partition keys up to 2KB). Version 1 is limited to 100 bytes. +- **Name is the resource ID**: The `resource.id` property MUST match the `name` parameter. +- **Hot partitions**: If one partition key value receives disproportionate traffic, it becomes a bottleneck. Design for even distribution. + +## Production Backlog Items +- Custom indexing policy to optimize for specific query patterns and reduce RU cost +- Time-to-live (TTL) for automatic data expiration +- Unique key constraints for data integrity +- Change feed for event-driven processing +- Composite indexes for multi-field ORDER BY queries diff --git a/azext_prototype/knowledge/services/cosmos-db-sql-database.md b/azext_prototype/knowledge/services/cosmos-db-sql-database.md new file mode 100644 index 0000000..4e0040e --- /dev/null +++ b/azext_prototype/knowledge/services/cosmos-db-sql-database.md @@ -0,0 +1,109 @@ +--- +service_namespace: Microsoft.DocumentDB/databaseAccounts/sqlDatabases +display_name: Cosmos DB SQL Database +depends_on: + - Microsoft.DocumentDB/databaseAccounts +--- + +# Cosmos DB SQL Database + +> A logical container within a Cosmos DB account that groups collections/containers and defines throughput sharing boundaries. + +## When to Use +- Every Cosmos DB application needs at least one database +- Use multiple databases to isolate workloads with different throughput or consistency requirements +- Database-level throughput sharing reduces cost when containers have variable load + +## POC Defaults +- **Throughput**: Serverless (no provisioned throughput needed for POC) +- **Name**: Application-specific (e.g., `kanflow`, `myapp`) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "cosmos_database" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.database_name + } + } + } + + response_export_values = ["*"] +} +``` + +### RBAC Assignment +```hcl +# Cosmos DB data-plane access uses Cosmos-specific RBAC (sqlRoleAssignments), +# NOT Microsoft.Authorization/roleAssignments. See the sqlRoleAssignments +# knowledge file for the correct pattern. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param databaseName string + +resource cosmosDatabase 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: databaseName + properties: { + resource: { + id: databaseName + } + } +} + +output databaseId string = cosmosDatabase.id +output databaseName string = cosmosDatabase.name +``` + +## Application Code + +### Python +```python +from azure.cosmos import CosmosClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = CosmosClient(url=cosmos_endpoint, credential=credential) +database = client.get_database_client(database_name) +``` + +### C# +```csharp +using Azure.Identity; +using Microsoft.Azure.Cosmos; + +var credential = new DefaultAzureCredential(); +var client = new CosmosClient(cosmosEndpoint, credential); +var database = client.GetDatabase(databaseName); +``` + +### Node.js +```typescript +import { CosmosClient } from "@azure/cosmos"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const client = new CosmosClient({ endpoint: cosmosEndpoint, aadCredentials: credential }); +const database = client.database(databaseName); +``` + +## Common Pitfalls +- **Database vs container throughput**: If using provisioned throughput, choose database-level sharing carefully — one hot container can starve others. +- **Serverless requires EnableServerless capability**: The parent Cosmos account must have `capabilities = [{ name = "EnableServerless" }]` for serverless databases. +- **Name is the resource ID**: The `resource.id` property MUST match the `name` parameter. + +## Production Backlog Items +- Provisioned throughput with autoscale for predictable performance +- Multiple databases for workload isolation +- Backup and restore configuration at the database level diff --git a/azext_prototype/knowledge/services/cosmos-db-sql-role-assignment.md b/azext_prototype/knowledge/services/cosmos-db-sql-role-assignment.md new file mode 100644 index 0000000..7799e40 --- /dev/null +++ b/azext_prototype/knowledge/services/cosmos-db-sql-role-assignment.md @@ -0,0 +1,113 @@ +--- +service_namespace: Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments +display_name: Cosmos DB SQL Role Assignment +depends_on: + - Microsoft.DocumentDB/databaseAccounts + - Microsoft.ManagedIdentity/userAssignedIdentities +--- + +# Cosmos DB SQL Role Assignment + +> Grants data-plane access (read/write) to a Cosmos DB account using Cosmos-specific RBAC — NOT standard Azure RBAC. + +## When to Use +- Every application identity that reads or writes Cosmos DB data needs a sqlRoleAssignment +- This is the ONLY way to grant data-plane access when local auth is disabled +- Standard `Microsoft.Authorization/roleAssignments` do NOT work for Cosmos DB data access + +## POC Defaults +- **Role**: Data Contributor (`00000000-0000-0000-0000-000000000002`) for read/write +- **Scope**: Account level (covers all databases and containers) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "cosmos_role_assignment" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15" + name = uuidv5("sha1", "${azapi_resource.cosmos_account.id}-${var.principal_id}-data-contributor") + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + roleDefinitionId = "${azapi_resource.cosmos_account.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002" + principalId = var.principal_id + scope = azapi_resource.cosmos_account.id + } + } +} +``` + +### Built-in Role Definition IDs +```hcl +# Data Reader: 00000000-0000-0000-0000-000000000001 +# Data Contributor: 00000000-0000-0000-0000-000000000002 +``` + +### RBAC Assignment +```hcl +# This IS the RBAC assignment. Cosmos DB uses its own role system, +# not Microsoft.Authorization/roleAssignments. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param principalId string + +var dataContributorRoleId = '00000000-0000-0000-0000-000000000002' + +resource cosmosRoleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = { + parent: cosmosAccount + name: guid(cosmosAccount.id, principalId, dataContributorRoleId) + properties: { + roleDefinitionId: '${cosmosAccount.id}/sqlRoleDefinitions/${dataContributorRoleId}' + principalId: principalId + scope: cosmosAccount.id + } +} +``` + +## Application Code + +### Python +```python +# No application code needed — the role assignment is an infrastructure concern. +# Once assigned, DefaultAzureCredential automatically authenticates: +from azure.cosmos import CosmosClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = CosmosClient(url=endpoint, credential=credential) +# Data access works automatically via the sqlRoleAssignment +``` + +### C# +```csharp +// No application code needed — once the role is assigned, +// DefaultAzureCredential handles authentication automatically: +var credential = new DefaultAzureCredential(); +var client = new CosmosClient(endpoint, credential); +// Data access works automatically via the sqlRoleAssignment +``` + +### Node.js +```typescript +// No application code needed — once the role is assigned, +// DefaultAzureCredential handles authentication automatically: +const credential = new DefaultAzureCredential(); +const client = new CosmosClient({ endpoint, aadCredentials: credential }); +``` + +## Common Pitfalls +- **Using ARM roleAssignments for data access**: `Microsoft.Authorization/roleAssignments` with "Cosmos DB Account Contributor" is a CONTROL PLANE role. It does NOT grant data read/write. You MUST use `sqlRoleAssignments`. +- **roleDefinitionId format**: Must be the full path including the account ID: `{accountId}/sqlRoleDefinitions/{roleId}`. +- **Scope must be account-level or lower**: The scope cannot be a subscription or resource group — it must be the Cosmos account ID or a database/container within it. +- **Duplicate assignments**: Re-applying the same role assignment with a different name creates a duplicate (no upsert). Use deterministic names via `uuidv5`. +- **Propagation delay**: Role assignments can take up to 10 minutes to propagate. Applications may get 403 errors during this window. + +## Production Backlog Items +- Scope role assignments to specific databases or containers instead of account level +- Separate reader and contributor roles for different application components +- Custom role definitions for fine-grained access control diff --git a/azext_prototype/knowledge/services/cosmos-db.md b/azext_prototype/knowledge/services/cosmos-db.md index a5237ad..5a33f93 100644 --- a/azext_prototype/knowledge/services/cosmos-db.md +++ b/azext_prototype/knowledge/services/cosmos-db.md @@ -1,331 +1,422 @@ -# Azure Cosmos DB (NoSQL API) - -> Globally distributed, multi-model database with single-digit millisecond latency and automatic scaling. - -## When to Use -- Applications needing low-latency reads/writes with global distribution -- Document-oriented or key-value data models with flexible schemas -- Event-driven architectures requiring change feed for real-time processing - -## POC Defaults -- **Capacity mode**: Serverless (no provisioned throughput to manage, pay-per-request) -- **Consistency level**: Session (best balance of consistency and performance for POCs) -- **API**: NoSQL (SQL-like query syntax, broadest SDK support) -- **Backup**: Continuous (default for serverless) - -## Terraform Patterns - -### Basic Resource -```hcl -resource "azurerm_cosmosdb_account" "this" { - name = var.cosmos_account_name - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - offer_type = "Standard" - kind = "GlobalDocumentDB" - local_authentication_disabled = true # Enforce RBAC-only access - - capabilities { - name = "EnableServerless" - } - - consistency_policy { - consistency_level = "Session" - } - - geo_location { - location = azurerm_resource_group.this.location - failover_priority = 0 - } - - tags = var.tags -} - -resource "azurerm_cosmosdb_sql_database" "this" { - name = var.database_name - resource_group_name = azurerm_resource_group.this.name - account_name = azurerm_cosmosdb_account.this.name -} - -resource "azurerm_cosmosdb_sql_container" "this" { - name = var.container_name - resource_group_name = azurerm_resource_group.this.name - account_name = azurerm_cosmosdb_account.this.name - database_name = azurerm_cosmosdb_sql_database.this.name - partition_key_paths = ["/partitionKey"] - - indexing_policy { - indexing_mode = "consistent" - - included_path { - path = "/*" - } - - excluded_path { - path = "/\"_etag\"/?" - } - } -} -``` - -### RBAC Assignment -```hcl -# CRITICAL: Cosmos DB uses its OWN role assignment resource, NOT azurerm_role_assignment. -# The built-in role definition IDs are: -# Reader: 00000000-0000-0000-0000-000000000001 -# Contributor: 00000000-0000-0000-0000-000000000002 - -resource "azurerm_cosmosdb_sql_role_assignment" "data_contributor" { - resource_group_name = azurerm_resource_group.this.name - account_name = azurerm_cosmosdb_account.this.name - role_definition_id = "${azurerm_cosmosdb_account.this.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002" - principal_id = azurerm_user_assigned_identity.this.principal_id - scope = azurerm_cosmosdb_account.this.id -} - -resource "azurerm_cosmosdb_sql_role_assignment" "data_reader" { - resource_group_name = azurerm_resource_group.this.name - account_name = azurerm_cosmosdb_account.this.name - role_definition_id = "${azurerm_cosmosdb_account.this.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000001" - principal_id = azurerm_user_assigned_identity.this.principal_id - scope = azurerm_cosmosdb_account.this.id -} -``` - -### Private Endpoint -```hcl -resource "azurerm_private_endpoint" "cosmos" { - name = "${var.cosmos_account_name}-pe" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - subnet_id = azurerm_subnet.private_endpoints.id - - private_service_connection { - name = "${var.cosmos_account_name}-psc" - private_connection_resource_id = azurerm_cosmosdb_account.this.id - is_manual_connection = false - subresource_names = ["Sql"] # Capital 'S' — this is required - } - - private_dns_zone_group { - name = "default" - private_dns_zone_ids = [azurerm_private_dns_zone.cosmos.id] - } -} - -resource "azurerm_private_dns_zone" "cosmos" { - name = "privatelink.documents.azure.com" - resource_group_name = azurerm_resource_group.this.name -} - -resource "azurerm_private_dns_zone_virtual_network_link" "cosmos" { - name = "cosmos-dns-link" - resource_group_name = azurerm_resource_group.this.name - private_dns_zone_name = azurerm_private_dns_zone.cosmos.name - virtual_network_id = azurerm_virtual_network.this.id -} -``` - -## Bicep Patterns - -### Basic Resource -```bicep -param cosmosAccountName string -param location string = resourceGroup().location -param databaseName string -param containerName string -param tags object = {} - -resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { - name: cosmosAccountName - location: location - kind: 'GlobalDocumentDB' - properties: { - databaseAccountOfferType: 'Standard' - disableLocalAuth: true // Enforce RBAC-only access - capabilities: [ - { - name: 'EnableServerless' - } - ] - consistencyPolicy: { - defaultConsistencyLevel: 'Session' - } - locations: [ - { - locationName: location - failoverPriority: 0 - } - ] - } - tags: tags -} - -resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { - parent: cosmosAccount - name: databaseName - properties: { - resource: { - id: databaseName - } - } -} - -resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/sqlContainers@2024-05-15' = { - parent: database - name: containerName - properties: { - resource: { - id: containerName - partitionKey: { - paths: ['/partitionKey'] - kind: 'Hash' - version: 2 - } - indexingPolicy: { - indexingMode: 'consistent' - includedPaths: [ - { path: '/*' } - ] - excludedPaths: [ - { path: '/"_etag"/?' } - ] - } - } - } -} -``` - -### RBAC Assignment -```bicep -// CRITICAL: Cosmos DB uses its own sqlRoleAssignment, NOT Microsoft.Authorization/roleAssignments. -// Built-in role definition IDs: -// Reader: 00000000-0000-0000-0000-000000000001 -// Contributor: 00000000-0000-0000-0000-000000000002 - -param principalId string - -var dataContributorRoleId = '00000000-0000-0000-0000-000000000002' - -resource roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = { - parent: cosmosAccount - name: guid(cosmosAccount.id, principalId, dataContributorRoleId) - properties: { - roleDefinitionId: '${cosmosAccount.id}/sqlRoleDefinitions/${dataContributorRoleId}' - principalId: principalId - scope: cosmosAccount.id - } -} -``` - -## Application Code - -### Python -```python -from azure.cosmos import CosmosClient -from azure.identity import DefaultAzureCredential - -credential = DefaultAzureCredential() -client = CosmosClient( - url="https://.documents.azure.com:443/", - credential=credential -) - -database = client.get_database_client("") -container = database.get_container_client("") - -# Create item -container.create_item(body={"id": "1", "partitionKey": "pk1", "name": "example"}) - -# Read item -item = container.read_item(item="1", partition_key="pk1") - -# Query items -items = list(container.query_items( - query="SELECT * FROM c WHERE c.partitionKey = @pk", - parameters=[{"name": "@pk", "value": "pk1"}], - enable_cross_partition_query=False -)) -``` - -### C# -```csharp -using Azure.Identity; -using Microsoft.Azure.Cosmos; - -var credential = new DefaultAzureCredential(); -var client = new CosmosClient( - accountEndpoint: "https://.documents.azure.com:443/", - tokenCredential: credential -); - -var database = client.GetDatabase(""); -var container = database.GetContainer(""); - -// Create item -var item = new { id = "1", partitionKey = "pk1", name = "example" }; -await container.CreateItemAsync(item, new PartitionKey("pk1")); - -// Read item -var response = await container.ReadItemAsync("1", new PartitionKey("pk1")); - -// Query items -var query = new QueryDefinition("SELECT * FROM c WHERE c.partitionKey = @pk") - .WithParameter("@pk", "pk1"); - -using var iterator = container.GetItemQueryIterator(query); -while (iterator.HasMoreResults) -{ - var results = await iterator.ReadNextAsync(); - foreach (var result in results) - { - Console.WriteLine(result); - } -} -``` - -### Node.js -```typescript -import { CosmosClient } from "@azure/cosmos"; -import { DefaultAzureCredential } from "@azure/identity"; - -const credential = new DefaultAzureCredential(); -const client = new CosmosClient({ - endpoint: "https://.documents.azure.com:443/", - aadCredentials: credential, -}); - -const database = client.database(""); -const container = database.container(""); - -// Create item -await container.items.create({ id: "1", partitionKey: "pk1", name: "example" }); - -// Read item -const { resource } = await container.item("1", "pk1").read(); - -// Query items -const { resources } = await container.items - .query({ - query: "SELECT * FROM c WHERE c.partitionKey = @pk", - parameters: [{ name: "@pk", value: "pk1" }], - }) - .fetchAll(); -``` - -## Common Pitfalls -- **MOST COMMON MISTAKE**: Using `azurerm_role_assignment` for data-plane RBAC. Cosmos DB requires `azurerm_cosmosdb_sql_role_assignment` with its own built-in role definition IDs (`00000000-0000-0000-0000-000000000001` for reader, `00000000-0000-0000-0000-000000000002` for contributor). The scope must be the Cosmos account ID, not a resource group. -- **Forgetting to disable local auth**: Set `local_authentication_disabled = true` (Terraform) or `disableLocalAuth: true` (Bicep) to enforce RBAC-only. Without this, key-based access remains available. -- **Private endpoint subresource**: The group ID is `Sql` with a capital `S`, not `sql` or `SQL`. -- **Partition key immutability**: Once a container is created with a partition key, it cannot be changed. Choose carefully before creating containers. -- **Serverless limitations**: Serverless accounts are single-region only and have a 1 MB max document size. Cannot convert between serverless and provisioned after creation. -- **Consistency level confusion**: Account-level consistency is the default; clients can relax (weaken) but not strengthen it per request. - -## Production Backlog Items -- Geo-replication with multi-region writes for high availability -- Autoscale throughput (switch from serverless to provisioned autoscale for predictable workloads) -- Custom backup policy with point-in-time restore configuration -- Partition key optimization based on actual query patterns -- Analytical store (HTAP) for large-scale analytics without impacting transactional workload -- Diagnostic settings for monitoring RU consumption and throttling -- Network restrictions (IP firewall rules, VNet service endpoints) +--- +service_namespace: Microsoft.DocumentDB/databaseAccounts +display_name: Azure Cosmos DB +--- + +# Azure Cosmos DB (NoSQL API) + +> Globally distributed, multi-model database with single-digit millisecond latency and automatic scaling. + +## When to Use +- Applications needing low-latency reads/writes with global distribution +- Document-oriented or key-value data models with flexible schemas +- Event-driven architectures requiring change feed for real-time processing + +## POC Defaults +- **Capacity mode**: Serverless (no provisioned throughput to manage, pay-per-request) +- **Consistency level**: Session (best balance of consistency and performance for POCs) +- **API**: NoSQL (SQL-like query syntax, broadest SDK support) +- **Backup**: Continuous (default for serverless) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "cosmos_account" { + type = "Microsoft.DocumentDB/databaseAccounts@2024-05-15" + name = var.cosmos_account_name + location = azapi_resource.resource_group.output.location + parent_id = azapi_resource.resource_group.id + + body = { + kind = "GlobalDocumentDB" + properties = { + databaseAccountOfferType = "Standard" + disableLocalAuth = true # Enforce RBAC-only access + capabilities = [ + { + name = "EnableServerless" + } + ] + consistencyPolicy = { + defaultConsistencyLevel = "Session" + } + locations = [ + { + locationName = azapi_resource.resource_group.output.location + failoverPriority = 0 + } + ] + } + } + + tags = var.tags + + response_export_values = ["*"] +} + +resource "azapi_resource" "cosmos_sql_database" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15" + name = var.database_name + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + resource = { + id = var.database_name + } + } + } +} + +resource "azapi_resource" "cosmos_sql_container" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/sqlContainers@2024-05-15" + name = var.container_name + parent_id = azapi_resource.cosmos_sql_database.id + + body = { + properties = { + resource = { + id = var.container_name + partitionKey = { + paths = ["/partitionKey"] + kind = "Hash" + version = 2 + } + indexingPolicy = { + indexingMode = "consistent" + includedPaths = [ + { path = "/*" } + ] + excludedPaths = [ + { path = "/\"_etag\"/?" } + ] + } + } + } + } +} +``` + +### RBAC Assignment +```hcl +# CRITICAL: Cosmos DB uses its OWN sqlRoleAssignment resource, NOT Microsoft.Authorization/roleAssignments. +# The built-in role definition IDs are: +# Reader: 00000000-0000-0000-0000-000000000001 +# Contributor: 00000000-0000-0000-0000-000000000002 + +resource "azapi_resource" "cosmos_data_contributor" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15" + name = uuidv5("sha1", "${azapi_resource.cosmos_account.id}-contributor-${azapi_resource.user_assigned_identity.output.properties.principalId}") + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + roleDefinitionId = "${azapi_resource.cosmos_account.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002" + principalId = azapi_resource.user_assigned_identity.output.properties.principalId + scope = azapi_resource.cosmos_account.id + } + } +} + +resource "azapi_resource" "cosmos_data_reader" { + type = "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15" + name = uuidv5("sha1", "${azapi_resource.cosmos_account.id}-reader-${azapi_resource.user_assigned_identity.output.properties.principalId}") + parent_id = azapi_resource.cosmos_account.id + + body = { + properties = { + roleDefinitionId = "${azapi_resource.cosmos_account.id}/sqlRoleDefinitions/00000000-0000-0000-0000-000000000001" + principalId = azapi_resource.user_assigned_identity.output.properties.principalId + scope = azapi_resource.cosmos_account.id + } + } +} +``` + +### Private Endpoint +```hcl +resource "azapi_resource" "cosmos_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "${var.cosmos_account_name}-pe" + location = azapi_resource.resource_group.output.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = azapi_resource.private_endpoints_subnet.id + } + privateLinkServiceConnections = [ + { + name = "${var.cosmos_account_name}-psc" + properties = { + privateLinkServiceId = azapi_resource.cosmos_account.id + groupIds = ["Sql"] # Capital 'S' — this is required + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "cosmos_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.documents.azure.com" + location = "global" + parent_id = azapi_resource.resource_group.id + + tags = var.tags +} + +resource "azapi_resource" "cosmos_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "cosmos-dns-link" + location = "global" + parent_id = azapi_resource.cosmos_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = azapi_resource.virtual_network.id + } + registrationEnabled = false + } + } + + tags = var.tags +} + +resource "azapi_resource" "cosmos_pe_dns_zone_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "default" + parent_id = azapi_resource.cosmos_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = azapi_resource.cosmos_dns_zone.id + } + } + ] + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param cosmosAccountName string +param location string = resourceGroup().location +param databaseName string +param containerName string +param tags object = {} + +resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = { + name: cosmosAccountName + location: location + kind: 'GlobalDocumentDB' + properties: { + databaseAccountOfferType: 'Standard' + disableLocalAuth: true // Enforce RBAC-only access + capabilities: [ + { + name: 'EnableServerless' + } + ] + consistencyPolicy: { + defaultConsistencyLevel: 'Session' + } + locations: [ + { + locationName: location + failoverPriority: 0 + } + ] + } + tags: tags +} + +resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2024-05-15' = { + parent: cosmosAccount + name: databaseName + properties: { + resource: { + id: databaseName + } + } +} + +resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/sqlContainers@2024-05-15' = { + parent: database + name: containerName + properties: { + resource: { + id: containerName + partitionKey: { + paths: ['/partitionKey'] + kind: 'Hash' + version: 2 + } + indexingPolicy: { + indexingMode: 'consistent' + includedPaths: [ + { path: '/*' } + ] + excludedPaths: [ + { path: '/"_etag"/?' } + ] + } + } + } +} +``` + +### RBAC Assignment +```bicep +// CRITICAL: Cosmos DB uses its own sqlRoleAssignment, NOT Microsoft.Authorization/roleAssignments. +// Built-in role definition IDs: +// Reader: 00000000-0000-0000-0000-000000000001 +// Contributor: 00000000-0000-0000-0000-000000000002 + +param principalId string + +var dataContributorRoleId = '00000000-0000-0000-0000-000000000002' + +resource roleAssignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = { + parent: cosmosAccount + name: guid(cosmosAccount.id, principalId, dataContributorRoleId) + properties: { + roleDefinitionId: '${cosmosAccount.id}/sqlRoleDefinitions/${dataContributorRoleId}' + principalId: principalId + scope: cosmosAccount.id + } +} +``` + +## Application Code + +### Python +```python +from azure.cosmos import CosmosClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = CosmosClient( + url="https://.documents.azure.com:443/", + credential=credential +) + +database = client.get_database_client("") +container = database.get_container_client("") + +# Create item +container.create_item(body={"id": "1", "partitionKey": "pk1", "name": "example"}) + +# Read item +item = container.read_item(item="1", partition_key="pk1") + +# Query items +items = list(container.query_items( + query="SELECT * FROM c WHERE c.partitionKey = @pk", + parameters=[{"name": "@pk", "value": "pk1"}], + enable_cross_partition_query=False +)) +``` + +### C# +```csharp +using Azure.Identity; +using Microsoft.Azure.Cosmos; + +var credential = new DefaultAzureCredential(); +var client = new CosmosClient( + accountEndpoint: "https://.documents.azure.com:443/", + tokenCredential: credential +); + +var database = client.GetDatabase(""); +var container = database.GetContainer(""); + +// Create item +var item = new { id = "1", partitionKey = "pk1", name = "example" }; +await container.CreateItemAsync(item, new PartitionKey("pk1")); + +// Read item +var response = await container.ReadItemAsync("1", new PartitionKey("pk1")); + +// Query items +var query = new QueryDefinition("SELECT * FROM c WHERE c.partitionKey = @pk") + .WithParameter("@pk", "pk1"); + +using var iterator = container.GetItemQueryIterator(query); +while (iterator.HasMoreResults) +{ + var results = await iterator.ReadNextAsync(); + foreach (var result in results) + { + Console.WriteLine(result); + } +} +``` + +### Node.js +```typescript +import { CosmosClient } from "@azure/cosmos"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const client = new CosmosClient({ + endpoint: "https://.documents.azure.com:443/", + aadCredentials: credential, +}); + +const database = client.database(""); +const container = database.container(""); + +// Create item +await container.items.create({ id: "1", partitionKey: "pk1", name: "example" }); + +// Read item +const { resource } = await container.item("1", "pk1").read(); + +// Query items +const { resources } = await container.items + .query({ + query: "SELECT * FROM c WHERE c.partitionKey = @pk", + parameters: [{ name: "@pk", value: "pk1" }], + }) + .fetchAll(); +``` + +## CRITICAL: Serverless Configuration +- Serverless mode is enabled via `capabilities`, **NOT** a `capacityMode` property +- CORRECT: `capabilities = [{ name = "EnableServerless" }]` +- WRONG: `capacityMode = "Serverless"` (this property does **NOT** exist in the ARM schema) +- For serverless accounts, **omit** the `backupPolicy` block entirely and let Azure use the + default. Specifying an incompatible backup type causes ARM deployment errors. +- For provisioned accounts, use `backupPolicy = { type = "Continuous", continuousModeProperties = { tier = "Continuous7Days" } }` for POC + +## Common Pitfalls +- **MOST COMMON MISTAKE**: Using `Microsoft.Authorization/roleAssignments` for data-plane RBAC. Cosmos DB requires `Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments` with its own built-in role definition IDs (`00000000-0000-0000-0000-000000000001` for reader, `00000000-0000-0000-0000-000000000002` for contributor). The scope must be the Cosmos account ID, not a resource group. +- **Forgetting to disable local auth**: Set `disableLocalAuth = true` in the `body.properties` block (Terraform azapi) or `disableLocalAuth: true` (Bicep) to enforce RBAC-only. Without this, key-based access remains available. +- **Private endpoint subresource**: The group ID is `Sql` with a capital `S`, not `sql` or `SQL`. +- **Partition key immutability**: Once a container is created with a partition key, it cannot be changed. Choose carefully before creating containers. +- **Serverless limitations**: Serverless accounts are single-region only and have a 1 MB max document size. Cannot convert between serverless and provisioned after creation. +- **Consistency level confusion**: Account-level consistency is the default; clients can relax (weaken) but not strengthen it per request. + +## Production Backlog Items +- Geo-replication with multi-region writes for high availability +- Autoscale throughput (switch from serverless to provisioned autoscale for predictable workloads) +- Custom backup policy with point-in-time restore configuration +- Partition key optimization based on actual query patterns +- Analytical store (HTAP) for large-scale analytics without impacting transactional workload +- Diagnostic settings for monitoring RU consumption and throttling +- Network restrictions (IP firewall rules, VNet service endpoints) diff --git a/azext_prototype/knowledge/services/data-factory-linked-service.md b/azext_prototype/knowledge/services/data-factory-linked-service.md new file mode 100644 index 0000000..7090501 --- /dev/null +++ b/azext_prototype/knowledge/services/data-factory-linked-service.md @@ -0,0 +1,178 @@ +--- +service_namespace: Microsoft.DataFactory/factories/linkedservices +display_name: Data Factory Linked Service +depends_on: + - Microsoft.DataFactory/factories +--- + +# Data Factory Linked Service + +> A connection definition within a Data Factory that specifies how to connect to an external data store or compute resource (Azure SQL, Blob Storage, REST APIs, etc.). + +## When to Use +- Connect Data Factory to source and destination data stores for data movement +- Authenticate to Azure services using managed identity (preferred) or connection strings +- Define compute contexts for data transformation (HDInsight, Databricks, Azure Batch) +- Every Data Factory pipeline that reads or writes data needs at least one linked service +- Reusable connection definitions shared across multiple pipelines and datasets + +## POC Defaults +- **Authentication**: Managed identity (for Azure services that support it) +- **Connect via integration runtime**: AutoResolveIntegrationRuntime (default) +- **Encryption**: In-transit encryption enabled + +## Terraform Patterns + +### Basic Resource +```hcl +# Blob Storage linked service with managed identity +resource "azapi_resource" "adf_ls_blob" { + type = "Microsoft.DataFactory/factories/linkedservices@2018-06-01" + name = var.linked_service_name + parent_id = azapi_resource.data_factory.id + + body = { + properties = { + type = "AzureBlobStorage" + typeProperties = { + serviceEndpoint = "https://${var.storage_account_name}.blob.core.windows.net" + } + connectVia = { + referenceName = "AutoResolveIntegrationRuntime" + type = "IntegrationRuntimeReference" + } + } + } +} + +# Azure SQL linked service with managed identity +resource "azapi_resource" "adf_ls_sql" { + type = "Microsoft.DataFactory/factories/linkedservices@2018-06-01" + name = "ls-azure-sql" + parent_id = azapi_resource.data_factory.id + + body = { + properties = { + type = "AzureSqlDatabase" + typeProperties = { + connectionString = "Server=tcp:${var.sql_server}.database.windows.net,1433;Database=${var.database};Authentication=Active Directory Managed Identity" + } + } + } +} +``` + +### RBAC Assignment +```hcl +# The Data Factory managed identity needs access to the target resource. +# For Blob Storage: Storage Blob Data Contributor +# For Azure SQL: db_datareader/db_datawriter roles via SQL +resource "azapi_resource" "adf_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.role_assignment_name + parent_id = azapi_resource.storage_account.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" + principalId = azapi_resource.data_factory.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param linkedServiceName string +param storageAccountName string + +resource linkedService 'Microsoft.DataFactory/factories/linkedservices@2018-06-01' = { + parent: dataFactory + name: linkedServiceName + properties: { + type: 'AzureBlobStorage' + typeProperties: { + serviceEndpoint: 'https://${storageAccountName}.blob.core.windows.net' + } + connectVia: { + referenceName: 'AutoResolveIntegrationRuntime' + type: 'IntegrationRuntimeReference' + } + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.datafactory import DataFactoryManagementClient + +credential = DefaultAzureCredential() +client = DataFactoryManagementClient(credential, subscription_id) + +# Create a linked service programmatically +from azure.mgmt.datafactory.models import LinkedServiceResource, AzureBlobStorageLinkedService + +ls = client.linked_services.create_or_update( + rg_name, factory_name, "ls-blob", + LinkedServiceResource( + properties=AzureBlobStorageLinkedService( + service_endpoint=f"https://{storage_account}.blob.core.windows.net" + ) + ) +) +print(f"Linked service: {ls.name}") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.DataFactory; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var factory = client.GetDataFactoryResource( + DataFactoryResource.CreateResourceIdentifier(subscriptionId, rgName, factoryName)); +var linkedServices = factory.GetDataFactoryLinkedServices(); + +// Linked services are typically managed via IaC, not runtime code +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { DataFactoryManagementClient } from "@azure/arm-datafactory"; + +const credential = new DefaultAzureCredential(); +const client = new DataFactoryManagementClient(credential, subscriptionId); + +await client.linkedServices.createOrUpdate(rgName, factoryName, "ls-blob", { + properties: { + type: "AzureBlobStorage", + typeProperties: { + serviceEndpoint: `https://${storageAccount}.blob.core.windows.net`, + }, + }, +}); +``` + +## Common Pitfalls +- **Managed identity permissions**: The Data Factory's managed identity must have the correct role on the target resource. Missing permissions cause runtime failures, not deployment failures. +- **API version is 2018-06-01**: Despite being old, this is the current stable API version for Data Factory child resources. Newer versions may not be available. +- **Type-specific properties**: Each linked service type has different `typeProperties`. Using wrong properties for the type causes validation errors. +- **Key Vault for secrets**: Connection strings with passwords should reference Azure Key Vault secrets, not inline values. Use `AzureKeyVaultSecretReference` in `typeProperties`. +- **Integration runtime**: For on-premises or VNet-connected sources, you need a self-hosted integration runtime, not the default AutoResolve. + +## Production Backlog Items +- Key Vault integration for secret management in linked services +- Self-hosted integration runtime for on-premises data sources +- Parameterized linked services for environment-specific connections +- Managed VNet integration runtime for network-isolated access +- Linked service testing and connectivity validation automation diff --git a/azext_prototype/knowledge/services/data-factory-pipeline.md b/azext_prototype/knowledge/services/data-factory-pipeline.md new file mode 100644 index 0000000..da29f4f --- /dev/null +++ b/azext_prototype/knowledge/services/data-factory-pipeline.md @@ -0,0 +1,174 @@ +--- +service_namespace: Microsoft.DataFactory/factories/pipelines +display_name: Data Factory Pipeline +depends_on: + - Microsoft.DataFactory/factories +--- + +# Data Factory Pipeline + +> A logical grouping of activities within a Data Factory that together perform a data movement or transformation task. Pipelines orchestrate Copy, DataFlow, and custom activities. + +## When to Use +- Orchestrate data movement between data stores (ETL/ELT pipelines) +- Chain multiple activities with dependency logic (success, failure, completion) +- Schedule recurring data integration jobs +- Parameterize data workflows for reuse across environments +- Combine Copy activities, Data Flows, and stored procedure calls + +## POC Defaults +- **Concurrency**: 1 (single concurrent run) +- **Annotations**: Empty +- **Activities**: Copy activity with source and sink datasets + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "adf_pipeline" { + type = "Microsoft.DataFactory/factories/pipelines@2018-06-01" + name = var.pipeline_name + parent_id = azapi_resource.data_factory.id + + body = { + properties = { + description = var.description + concurrency = 1 + parameters = { + sourcePath = { type = "String", defaultValue = "input" } + sinkPath = { type = "String", defaultValue = "output" } + } + activities = [ + { + name = "CopyBlobToBlob" + type = "Copy" + inputs = [ + { referenceName = "SourceDataset", type = "DatasetReference" } + ] + outputs = [ + { referenceName = "SinkDataset", type = "DatasetReference" } + ] + typeProperties = { + source = { type = "BlobSource" } + sink = { type = "BlobSink" } + } + } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Data Factory Contributor role allows pipeline management. +# Pipeline execution uses the Data Factory managed identity's permissions. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param pipelineName string + +resource pipeline 'Microsoft.DataFactory/factories/pipelines@2018-06-01' = { + parent: dataFactory + name: pipelineName + properties: { + description: 'Copy data from source to sink' + concurrency: 1 + parameters: { + sourcePath: { type: 'String', defaultValue: 'input' } + sinkPath: { type: 'String', defaultValue: 'output' } + } + activities: [ + { + name: 'CopyBlobToBlob' + type: 'Copy' + inputs: [ + { referenceName: 'SourceDataset', type: 'DatasetReference' } + ] + outputs: [ + { referenceName: 'SinkDataset', type: 'DatasetReference' } + ] + typeProperties: { + source: { type: 'BlobSource' } + sink: { type: 'BlobSink' } + } + } + ] + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.datafactory import DataFactoryManagementClient + +credential = DefaultAzureCredential() +client = DataFactoryManagementClient(credential, subscription_id) + +# Trigger a pipeline run +run = client.pipelines.create_run( + rg_name, factory_name, pipeline_name, + parameters={"sourcePath": "data/2025", "sinkPath": "archive/2025"} +) +print(f"Pipeline run ID: {run.run_id}") + +# Monitor the run +import time +while True: + status = client.pipeline_runs.get(rg_name, factory_name, run.run_id) + print(f"Status: {status.status}") + if status.status in ("Succeeded", "Failed", "Cancelled"): + break + time.sleep(10) +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.DataFactory; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var factory = client.GetDataFactoryResource( + DataFactoryResource.CreateResourceIdentifier(subscriptionId, rgName, factoryName)); +var pipeline = await factory.GetDataFactoryPipelineAsync(pipelineName); + +// Trigger pipeline run via REST API or SDK +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { DataFactoryManagementClient } from "@azure/arm-datafactory"; + +const credential = new DefaultAzureCredential(); +const client = new DataFactoryManagementClient(credential, subscriptionId); + +const run = await client.pipelines.createRun(rgName, factoryName, pipelineName, { + parameters: { sourcePath: "data/2025", sinkPath: "archive/2025" }, +}); +console.log(`Pipeline run ID: ${run.runId}`); +``` + +## Common Pitfalls +- **Datasets must exist**: Pipelines reference datasets by name. If the referenced datasets don't exist, pipeline deployment succeeds but execution fails. +- **Activity dependencies**: Without explicit dependencies, activities run in parallel. Use `dependsOn` with conditions (Succeeded, Failed, Completed, Skipped) for ordering. +- **API version is 2018-06-01**: This is the current stable API for Data Factory pipeline resources. Don't use newer API versions. +- **JSON complexity**: Pipeline definitions can be very large. For complex pipelines, consider managing them via the ADF UI and exporting ARM templates. +- **Trigger vs manual run**: Deploying a pipeline doesn't start it. You need a trigger resource or manual `createRun` API call to execute. +- **Concurrency limit**: The `concurrency` property limits simultaneous runs. Set to 1 to prevent overlapping runs of the same pipeline. + +## Production Backlog Items +- Trigger configuration (schedule, tumbling window, event-based) +- Error handling with retry policies and failure activities +- Parameterized pipelines for environment promotion (dev → staging → prod) +- Monitoring and alerting for pipeline failures +- Data lineage tracking with Azure Purview integration diff --git a/azext_prototype/knowledge/services/data-factory.md b/azext_prototype/knowledge/services/data-factory.md index f7b4035..0746fea 100644 --- a/azext_prototype/knowledge/services/data-factory.md +++ b/azext_prototype/knowledge/services/data-factory.md @@ -1,329 +1,412 @@ -# Azure Data Factory -> Cloud-based ETL/ELT service for orchestrating data integration pipelines at scale with 100+ built-in connectors and visual authoring. - -## When to Use - -- **Data integration** -- move and transform data between Azure services, on-premises databases, SaaS applications, and cloud storage -- **ETL/ELT orchestration** -- scheduled or event-driven pipelines for data warehousing and analytics -- **Data migration** -- bulk copy from on-premises to Azure (SQL Server → Azure SQL, files → Blob/ADLS) -- **Hybrid connectivity** -- connect to on-premises data sources via self-hosted integration runtime -- **Low-code data workflows** -- visual pipeline designer with mapping data flows for transformations - -Choose Data Factory over Fabric Data Pipelines when you need ARM-level control, VNet integration, or have existing ADF investments. Choose Fabric when you want unified analytics with Spark, warehousing, and BI in one platform. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Version | V2 | V1 is deprecated | -| Integration runtime | Azure (auto-resolve) | Managed; no infrastructure to maintain | -| Data flow compute | General Purpose, 8 cores | Minimum for mapping data flows | -| Git integration | Disabled (POC) | Enable for production CI/CD | -| Managed VNet | Disabled (POC) | Flag as production backlog item | -| Public network access | Enabled (POC) | Flag private endpoint as production backlog item | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_data_factory" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - - identity { - type = "SystemAssigned" - } - - public_network_enabled = true # Set false when using private endpoint - - tags = var.tags -} -``` - -### Linked Service (Azure SQL) - -```hcl -resource "azurerm_data_factory_linked_service_azure_sql_database" "this" { - name = "ls-azuresql" - data_factory_id = azurerm_data_factory.this.id - connection_string = "Integrated Security=False;Data Source=${var.sql_server_fqdn};Initial Catalog=${var.database_name};" - use_managed_identity = true # Authenticate via ADF managed identity -} -``` - -### Linked Service (Blob Storage) - -```hcl -resource "azurerm_data_factory_linked_service_azure_blob_storage" "this" { - name = "ls-blob" - data_factory_id = azurerm_data_factory.this.id - service_endpoint = "https://${var.storage_account_name}.blob.core.windows.net" - use_managed_identity = true -} -``` - -### Pipeline with Copy Activity - -```hcl -resource "azurerm_data_factory_pipeline" "copy" { - name = "pl-copy-data" - data_factory_id = azurerm_data_factory.this.id - - activities_json = jsonencode([ - { - name = "CopyFromBlobToSQL" - type = "Copy" - inputs = [{ referenceName = "ds-blob-csv", type = "DatasetReference" }] - outputs = [{ referenceName = "ds-sql-table", type = "DatasetReference" }] - typeProperties = { - source = { type = "DelimitedTextSource" } - sink = { type = "AzureSqlSink", writeBehavior = "upsert", upsertSettings = { useTempDB = true } } - } - } - ]) -} -``` - -### RBAC Assignment - -```hcl -# Data Factory Contributor -- manage pipelines and triggers -resource "azurerm_role_assignment" "adf_contributor" { - scope = azurerm_data_factory.this.id - role_definition_name = "Data Factory Contributor" - principal_id = var.admin_identity_principal_id -} - -# Grant ADF's managed identity access to data sources -resource "azurerm_role_assignment" "adf_blob_reader" { - scope = var.storage_account_id - role_definition_name = "Storage Blob Data Reader" - principal_id = azurerm_data_factory.this.identity[0].principal_id -} - -resource "azurerm_role_assignment" "adf_blob_contributor" { - scope = var.storage_account_id - role_definition_name = "Storage Blob Data Contributor" - principal_id = azurerm_data_factory.this.identity[0].principal_id -} -``` - -RBAC role IDs: -- Data Factory Contributor: `673868aa-7521-48a0-acc6-0f60742d39f5` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "adf" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_data_factory.this.id - subresource_names = ["dataFactory"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.datafactory.azure.net` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Data Factory') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Tags to apply') -param tags object = {} - -resource adf 'Microsoft.DataFactory/factories@2018-06-01' = { - name: name - location: location - tags: tags - identity: { - type: 'SystemAssigned' - } - properties: { - publicNetworkAccess: 'Enabled' - } -} - -output id string = adf.id -output name string = adf.name -output principalId string = adf.identity.principalId -``` - -### Linked Service (Bicep) - -```bicep -resource blobLinkedService 'Microsoft.DataFactory/factories/linkedservices@2018-06-01' = { - parent: adf - name: 'ls-blob' - properties: { - type: 'AzureBlobStorage' - typeProperties: { - serviceEndpoint: 'https://${storageAccountName}.blob.core.windows.net' - } - connectVia: { - referenceName: 'AutoResolveIntegrationRuntime' - type: 'IntegrationRuntimeReference' - } - } -} -``` - -### RBAC Assignment - -```bicep -@description('Storage account ID for data source access') -param storageAccountId string - -var blobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1' - -resource blobReaderAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(storageAccountId, adf.identity.principalId, blobDataReaderRoleId) - scope: resourceId('Microsoft.Storage/storageAccounts', split(storageAccountId, '/')[8]) - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', blobDataReaderRoleId) - principalId: adf.identity.principalId - principalType: 'ServicePrincipal' - } -} -``` - -### Private Endpoint - -```bicep -@description('Subnet ID for private endpoint') -param subnetId string = '' - -resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { - name: 'pe-${name}' - location: location - tags: tags - properties: { - subnet: { - id: subnetId - } - privateLinkServiceConnections: [ - { - name: 'psc-${name}' - properties: { - privateLinkServiceId: adf.id - groupIds: ['dataFactory'] - } - } - ] - } -} -``` - -## Application Code - -Data Factory is a visual/declarative service -- pipelines are authored in the ADF Studio UI or as JSON/ARM templates. Application code interacts with ADF through SDKs for monitoring and triggering. - -### Python — Trigger Pipeline Run - -```python -from azure.identity import DefaultAzureCredential -from azure.mgmt.datafactory import DataFactoryManagementClient - -credential = DefaultAzureCredential() -client = DataFactoryManagementClient(credential, subscription_id) - -# Trigger a pipeline run -run = client.pipelines.create_run( - resource_group_name="my-rg", - factory_name="my-adf", - pipeline_name="pl-copy-data", - parameters={"inputPath": "raw/2024/01/"}, -) - -print(f"Pipeline run ID: {run.run_id}") - -# Monitor pipeline run -import time - -while True: - status = client.pipeline_runs.get("my-rg", "my-adf", run.run_id) - print(f"Status: {status.status}") - if status.status in ["Succeeded", "Failed", "Cancelled"]: - break - time.sleep(10) -``` - -### C# — Trigger Pipeline Run - -```csharp -using Azure.Identity; -using Azure.ResourceManager; -using Azure.ResourceManager.DataFactory; - -var credential = new DefaultAzureCredential(); -var armClient = new ArmClient(credential); - -var factory = armClient.GetDataFactoryResource( - DataFactoryResource.CreateResourceIdentifier(subscriptionId, "my-rg", "my-adf") -); - -var pipeline = factory.GetDataFactoryPipeline("pl-copy-data"); -var runResponse = await pipeline.Value.CreateRunAsync(); -Console.WriteLine($"Pipeline run ID: {runResponse.Value.RunId}"); -``` - -### REST API — Trigger Pipeline - -```bash -# Trigger pipeline via REST API -curl -X POST \ - "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.DataFactory/factories/{factory}/pipelines/{pipeline}/createRun?api-version=2018-06-01" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"inputPath": "raw/2024/01/"}' -``` - -## Common Pitfalls - -1. **Self-hosted IR required for on-premises** -- Auto-resolve integration runtime cannot access on-premises data sources. Install self-hosted IR on a VM with network access to the source. -2. **Managed identity on linked services** -- Always use managed identity instead of connection strings or keys. Grant the ADF managed identity appropriate RBAC roles on each data source. -3. **Copy activity parallelism** -- Default DIU (Data Integration Unit) is 4. Increase for large datasets. Parallel copy degree defaults to auto but can be tuned. -4. **Mapping data flow cold start** -- First data flow execution in a session takes 3-5 minutes for cluster spin-up. Use TTL (time-to-live) settings to keep clusters warm. -5. **Git integration conflicts** -- ADF's Live mode and Git mode can diverge. Always publish from Git branches in production. For POC, Git integration can be added later. -6. **Trigger timezone** -- Schedule triggers use UTC by default. Specify timezone explicitly to avoid off-by-hours execution. -7. **Pipeline JSON is not idempotent in Terraform** -- `activities_json` changes on every plan due to ordering. Use `lifecycle { ignore_changes }` or manage pipelines outside Terraform. - -## Production Backlog Items - -- [ ] Enable managed VNet for secure data source connectivity -- [ ] Enable private endpoint and disable public network access -- [ ] Configure Git integration with Azure DevOps or GitHub -- [ ] Set up CI/CD deployment pipelines (ARM export → deploy) -- [ ] Configure managed private endpoints for data sources -- [ ] Enable diagnostic logging to Log Analytics -- [ ] Implement pipeline monitoring and alerting -- [ ] Configure self-hosted integration runtime for on-premises sources -- [ ] Set up data flow cluster TTL for performance -- [ ] Review and optimize DIU/parallelism settings for copy activities +--- +service_namespace: Microsoft.DataFactory/factories +display_name: Azure Data Factory +--- + +# Azure Data Factory +> Cloud-based ETL/ELT service for orchestrating data integration pipelines at scale with 100+ built-in connectors and visual authoring. + +## When to Use + +- **Data integration** -- move and transform data between Azure services, on-premises databases, SaaS applications, and cloud storage +- **ETL/ELT orchestration** -- scheduled or event-driven pipelines for data warehousing and analytics +- **Data migration** -- bulk copy from on-premises to Azure (SQL Server → Azure SQL, files → Blob/ADLS) +- **Hybrid connectivity** -- connect to on-premises data sources via self-hosted integration runtime +- **Low-code data workflows** -- visual pipeline designer with mapping data flows for transformations + +Choose Data Factory over Fabric Data Pipelines when you need ARM-level control, VNet integration, or have existing ADF investments. Choose Fabric when you want unified analytics with Spark, warehousing, and BI in one platform. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Version | V2 | V1 is deprecated | +| Integration runtime | Azure (auto-resolve) | Managed; no infrastructure to maintain | +| Data flow compute | General Purpose, 8 cores | Minimum for mapping data flows | +| Git integration | Disabled (POC) | Enable for production CI/CD | +| Managed VNet | Disabled (POC) | Flag as production backlog item | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.DataFactory/factories@2018-06-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### Linked Service (Azure SQL) + +```hcl +resource "azapi_resource" "ls_azuresql" { + type = "Microsoft.DataFactory/factories/linkedservices@2018-06-01" + name = "ls-azuresql" + parent_id = azapi_resource.this.id + + body = { + properties = { + type = "AzureSqlDatabase" + typeProperties = { + connectionString = "Integrated Security=False;Data Source=${var.sql_server_fqdn};Initial Catalog=${var.database_name};" + credential = { + referenceName = "ManagedIdentityCredential" + type = "CredentialReference" + } + } + } + } +} +``` + +### Linked Service (Blob Storage) + +```hcl +resource "azapi_resource" "ls_blob" { + type = "Microsoft.DataFactory/factories/linkedservices@2018-06-01" + name = "ls-blob" + parent_id = azapi_resource.this.id + + body = { + properties = { + type = "AzureBlobStorage" + typeProperties = { + serviceEndpoint = "https://${var.storage_account_name}.blob.core.windows.net" + credential = { + referenceName = "ManagedIdentityCredential" + type = "CredentialReference" + } + } + } + } +} +``` + +### Pipeline with Copy Activity + +```hcl +resource "azapi_resource" "pipeline_copy" { + type = "Microsoft.DataFactory/factories/pipelines@2018-06-01" + name = "pl-copy-data" + parent_id = azapi_resource.this.id + + body = { + properties = { + activities = [ + { + name = "CopyFromBlobToSQL" + type = "Copy" + inputs = [{ referenceName = "ds-blob-csv", type = "DatasetReference" }] + outputs = [{ referenceName = "ds-sql-table", type = "DatasetReference" }] + typeProperties = { + source = { type = "DelimitedTextSource" } + sink = { type = "AzureSqlSink", writeBehavior = "upsert", upsertSettings = { useTempDB = true } } + } + } + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# Data Factory Contributor -- manage pipelines and triggers +resource "azapi_resource" "adf_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-adf-contributor") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/673868aa-7521-48a0-acc6-0f60742d39f5" + principalId = var.admin_identity_principal_id + } + } +} + +# Grant ADF's managed identity access to data sources +resource "azapi_resource" "adf_blob_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}-blob-reader") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1" + principalId = azapi_resource.this.output.identity.principalId + } + } +} + +resource "azapi_resource" "adf_blob_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" + principalId = azapi_resource.this.output.identity.principalId + } + } +} +``` + +RBAC role IDs: +- Data Factory Contributor: `673868aa-7521-48a0-acc6-0f60742d39f5` + +### Private Endpoint + +```hcl +resource "azapi_resource" "adf_pe" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.this.id + groupIds = ["dataFactory"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "adf_pe_dns" { + count = var.enable_private_endpoint && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.adf_pe[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.datafactory.azure.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Data Factory') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource adf 'Microsoft.DataFactory/factories@2018-06-01' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + publicNetworkAccess: 'Disabled' // Unless told otherwise, disabled per governance policy + } +} + +output id string = adf.id +output name string = adf.name +output principalId string = adf.identity.principalId +``` + +### Linked Service (Bicep) + +```bicep +resource blobLinkedService 'Microsoft.DataFactory/factories/linkedservices@2018-06-01' = { + parent: adf + name: 'ls-blob' + properties: { + type: 'AzureBlobStorage' + typeProperties: { + serviceEndpoint: 'https://${storageAccountName}.blob.core.windows.net' + } + connectVia: { + referenceName: 'AutoResolveIntegrationRuntime' + type: 'IntegrationRuntimeReference' + } + } +} +``` + +### RBAC Assignment + +```bicep +@description('Storage account ID for data source access') +param storageAccountId string + +var blobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1' + +resource blobReaderAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(storageAccountId, adf.identity.principalId, blobDataReaderRoleId) + scope: resourceId('Microsoft.Storage/storageAccounts', split(storageAccountId, '/')[8]) + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', blobDataReaderRoleId) + principalId: adf.identity.principalId + principalType: 'ServicePrincipal' + } +} +``` + +### Private Endpoint + +```bicep +@description('Subnet ID for private endpoint') +param subnetId string = '' + +resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = if (!empty(subnetId)) { + name: 'pe-${name}' + location: location + tags: tags + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'psc-${name}' + properties: { + privateLinkServiceId: adf.id + groupIds: ['dataFactory'] + } + } + ] + } +} +``` + +## Application Code + +Data Factory is a visual/declarative service -- pipelines are authored in the ADF Studio UI or as JSON/ARM templates. Application code interacts with ADF through SDKs for monitoring and triggering. + +### Python — Trigger Pipeline Run + +```python +from azure.identity import DefaultAzureCredential +from azure.mgmt.datafactory import DataFactoryManagementClient + +credential = DefaultAzureCredential() +client = DataFactoryManagementClient(credential, subscription_id) + +# Trigger a pipeline run +run = client.pipelines.create_run( + resource_group_name="my-rg", + factory_name="my-adf", + pipeline_name="pl-copy-data", + parameters={"inputPath": "raw/2024/01/"}, +) + +print(f"Pipeline run ID: {run.run_id}") + +# Monitor pipeline run +import time + +while True: + status = client.pipeline_runs.get("my-rg", "my-adf", run.run_id) + print(f"Status: {status.status}") + if status.status in ["Succeeded", "Failed", "Cancelled"]: + break + time.sleep(10) +``` + +### C# — Trigger Pipeline Run + +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.DataFactory; + +var credential = new DefaultAzureCredential(); +var armClient = new ArmClient(credential); + +var factory = armClient.GetDataFactoryResource( + DataFactoryResource.CreateResourceIdentifier(subscriptionId, "my-rg", "my-adf") +); + +var pipeline = factory.GetDataFactoryPipeline("pl-copy-data"); +var runResponse = await pipeline.Value.CreateRunAsync(); +Console.WriteLine($"Pipeline run ID: {runResponse.Value.RunId}"); +``` + +### REST API — Trigger Pipeline + +```bash +# Trigger pipeline via REST API +curl -X POST \ + "https://management.azure.com/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.DataFactory/factories/{factory}/pipelines/{pipeline}/createRun?api-version=2018-06-01" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"inputPath": "raw/2024/01/"}' +``` + +## Common Pitfalls + +1. **Self-hosted IR required for on-premises** -- Auto-resolve integration runtime cannot access on-premises data sources. Install self-hosted IR on a VM with network access to the source. +2. **Managed identity on linked services** -- Always use managed identity instead of connection strings or keys. Grant the ADF managed identity appropriate RBAC roles on each data source. +3. **Copy activity parallelism** -- Default DIU (Data Integration Unit) is 4. Increase for large datasets. Parallel copy degree defaults to auto but can be tuned. +4. **Mapping data flow cold start** -- First data flow execution in a session takes 3-5 minutes for cluster spin-up. Use TTL (time-to-live) settings to keep clusters warm. +5. **Git integration conflicts** -- ADF's Live mode and Git mode can diverge. Always publish from Git branches in production. For POC, Git integration can be added later. +6. **Trigger timezone** -- Schedule triggers use UTC by default. Specify timezone explicitly to avoid off-by-hours execution. +7. **Pipeline JSON is not idempotent in Terraform** -- `activities_json` changes on every plan due to ordering. Use `lifecycle { ignore_changes }` or manage pipelines outside Terraform. + +## Production Backlog Items + +- [ ] Enable managed VNet for secure data source connectivity +- [ ] Enable private endpoint and disable public network access +- [ ] Configure Git integration with Azure DevOps or GitHub +- [ ] Set up CI/CD deployment pipelines (ARM export → deploy) +- [ ] Configure managed private endpoints for data sources +- [ ] Enable diagnostic logging to Log Analytics +- [ ] Implement pipeline monitoring and alerting +- [ ] Configure self-hosted integration runtime for on-premises sources +- [ ] Set up data flow cluster TTL for performance +- [ ] Review and optimize DIU/parallelism settings for copy activities diff --git a/azext_prototype/knowledge/services/databricks.md b/azext_prototype/knowledge/services/databricks.md index 76eaf59..70679bf 100644 --- a/azext_prototype/knowledge/services/databricks.md +++ b/azext_prototype/knowledge/services/databricks.md @@ -1,341 +1,423 @@ -# Azure Databricks -> Unified analytics platform for data engineering, data science, and machine learning built on Apache Spark with collaborative notebooks and Delta Lake. - -## When to Use - -- **Large-scale data processing** -- Spark-based ETL/ELT for petabyte-scale data -- **Machine learning** -- MLflow-based experiment tracking, model training, and deployment -- **Delta Lake** -- ACID transactions, schema enforcement, and time travel on data lakes -- **Real-time streaming** -- Structured Streaming for continuous data processing -- **Collaborative analytics** -- shared notebooks for data engineers, scientists, and analysts -- **Unity Catalog governance** -- centralized data cataloging, lineage, and access control - -Choose Databricks over Fabric when you need advanced Spark tuning, custom ML pipelines, multi-cloud portability, or have existing Databricks investments. Choose Fabric for simpler analytics with Power BI integration and T-SQL access. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Pricing tier | Premium | Required for Unity Catalog, RBAC; not significantly more expensive | -| Cluster type | Single-node | Smallest for development; no worker nodes | -| Node type | Standard_D4s_v5 | 4 vCPU, 16 GiB; good balance for POC | -| Auto-termination | 30 minutes | Prevent idle cluster costs | -| Runtime | Latest LTS | e.g., 14.3 LTS with Spark 3.5 | -| Unity Catalog | Enabled | Free with Premium tier; required for governance | -| Public network access | Enabled (POC) | Flag VNet injection as production backlog item | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_databricks_workspace" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - sku = "premium" # Required for Unity Catalog - managed_resource_group_name = "${var.resource_group_name}-databricks-managed" - public_network_access_enabled = true # Set false for VNet injection - - tags = var.tags -} -``` - -### VNet Injection - -```hcl -resource "azurerm_databricks_workspace" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - sku = "premium" - managed_resource_group_name = "${var.resource_group_name}-databricks-managed" - public_network_access_enabled = false - - custom_parameters { - virtual_network_id = var.vnet_id - public_subnet_name = var.public_subnet_name - private_subnet_name = var.private_subnet_name - public_subnet_network_security_group_association_id = var.public_nsg_association_id - private_subnet_network_security_group_association_id = var.private_nsg_association_id - no_public_ip = true # Secure cluster connectivity - } - - tags = var.tags -} -``` - -### Unity Catalog Metastore - -```hcl -# Storage account for Unity Catalog metastore -resource "azurerm_storage_account" "unity" { - name = var.unity_storage_name - resource_group_name = var.resource_group_name - location = var.location - account_tier = "Standard" - account_replication_type = "LRS" - is_hns_enabled = true # Hierarchical namespace (ADLS Gen2) - - tags = var.tags -} - -resource "azurerm_storage_container" "unity" { - name = "unity-catalog" - storage_account_name = azurerm_storage_account.unity.name - container_access_type = "private" -} - -# Unity Catalog metastore (via Databricks provider) -resource "databricks_metastore" "this" { - name = "poc-metastore" - storage_root = "abfss://unity-catalog@${azurerm_storage_account.unity.name}.dfs.core.windows.net/" - force_destroy = true # POC only - owner = var.admin_group_name -} - -resource "databricks_metastore_assignment" "this" { - workspace_id = azurerm_databricks_workspace.this.workspace_id - metastore_id = databricks_metastore.this.id - default_catalog_name = "main" -} -``` - -### RBAC Assignment - -```hcl -# Contributor on workspace (ARM-level management) -resource "azurerm_role_assignment" "dbw_contributor" { - scope = azurerm_databricks_workspace.this.id - role_definition_name = "Contributor" - principal_id = var.admin_identity_principal_id -} - -# Grant Databricks managed identity access to storage for Unity Catalog -resource "azurerm_role_assignment" "unity_blob_contributor" { - scope = azurerm_storage_account.unity.id - role_definition_name = "Storage Blob Data Contributor" - principal_id = databricks_metastore.this.delta_sharing_organization_name # Access connector ID -} -``` - -**Note:** Databricks uses its own ACL system for data-plane access (workspace groups, Unity Catalog grants). ARM RBAC controls management-plane access only. - -### Private Endpoint - -Databricks uses **VNet injection** (see above) rather than traditional private endpoints. For additional frontend private endpoint access: - -```hcl -resource "azurerm_private_endpoint" "databricks" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_databricks_workspace.this.id - subresource_names = ["databricks_ui_api"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.azuredatabricks.net` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Databricks workspace') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Managed resource group name') -param managedResourceGroupName string = '${resourceGroup().name}-databricks-managed' - -@description('Tags to apply') -param tags object = {} - -resource workspace 'Microsoft.Databricks/workspaces@2024-05-01' = { - name: name - location: location - tags: tags - sku: { - name: 'premium' - } - properties: { - managedResourceGroupId: subscriptionResourceId('Microsoft.Resources/resourceGroups', managedResourceGroupName) - publicNetworkAccess: 'Enabled' - requiredNsgRules: 'AllRules' - } -} - -output id string = workspace.id -output name string = workspace.name -output url string = 'https://${workspace.properties.workspaceUrl}' -output workspaceId string = workspace.properties.workspaceId -``` - -### VNet Injection (Bicep) - -```bicep -@description('VNet ID') -param vnetId string - -@description('Public subnet name') -param publicSubnetName string - -@description('Private subnet name') -param privateSubnetName string - -resource workspace 'Microsoft.Databricks/workspaces@2024-05-01' = { - name: name - location: location - tags: tags - sku: { - name: 'premium' - } - properties: { - managedResourceGroupId: subscriptionResourceId('Microsoft.Resources/resourceGroups', managedResourceGroupName) - publicNetworkAccess: 'Disabled' - requiredNsgRules: 'NoAzureDatabricksRules' - parameters: { - customVirtualNetworkId: { - value: vnetId - } - customPublicSubnetName: { - value: publicSubnetName - } - customPrivateSubnetName: { - value: privateSubnetName - } - enableNoPublicIp: { - value: true - } - } - } -} -``` - -### RBAC Assignment - -No data-plane RBAC via ARM -- use Databricks workspace ACLs and Unity Catalog grants. - -## Application Code - -### Python — Databricks SDK (External) - -```python -from databricks.sdk import WorkspaceClient - -# Authenticate using Azure AD (DefaultAzureCredential) -w = WorkspaceClient( - host="https://adb-1234567890.1.azuredatabricks.net", - azure_workspace_resource_id="/subscriptions/.../resourceGroups/.../providers/Microsoft.Databricks/workspaces/...", -) - -# List clusters -for c in w.clusters.list(): - print(f"{c.cluster_name}: {c.state}") - -# Run a notebook job -from databricks.sdk.service.jobs import Task, NotebookTask - -run = w.jobs.submit( - run_name="my-etl-job", - tasks=[ - Task( - task_key="etl", - existing_cluster_id="0123-456789-abcdef", - notebook_task=NotebookTask( - notebook_path="/Repos/etl/transform", - base_parameters={"date": "2024-01-01"}, - ), - ) - ], -).result() -``` - -### Python — Notebook Code (Databricks Runtime) - -```python -# Runs inside a Databricks notebook -# Unity Catalog table access -df = spark.read.table("main.default.customers") - -# Transform with Delta Lake -from pyspark.sql.functions import col, current_timestamp - -df_processed = ( - df.filter(col("status") == "active") - .withColumn("processed_at", current_timestamp()) -) - -# Write to Unity Catalog table -df_processed.write.mode("overwrite").saveAsTable("main.default.active_customers") - -# Access Azure Blob Storage via Unity Catalog external location -df_external = spark.read.format("csv").load("abfss://data@mystorageaccount.dfs.core.windows.net/raw/") -``` - -### SQL — Databricks SQL - -```sql --- Unity Catalog SQL queries -USE CATALOG main; -USE SCHEMA default; - -CREATE TABLE IF NOT EXISTS orders ( - order_id BIGINT GENERATED ALWAYS AS IDENTITY, - customer_id BIGINT, - total DECIMAL(10, 2), - created_at TIMESTAMP DEFAULT current_timestamp() -) -USING DELTA -TBLPROPERTIES ('delta.enableChangeDataFeed' = true); - --- Time travel -SELECT * FROM orders VERSION AS OF 5; -SELECT * FROM orders TIMESTAMP AS OF '2024-01-01T00:00:00Z'; -``` - -## Common Pitfalls - -1. **Managed resource group conflicts** -- Databricks creates a managed resource group for VMs, disks, and NSGs. The name must not already exist. Use a predictable naming convention. -2. **VNet injection subnet sizing** -- Each cluster node uses one IP. Public and private subnets need /26 minimum (64 IPs) for small clusters, /22 for production. Under-sized subnets cause cluster launch failures. -3. **Unity Catalog access connector** -- Unity Catalog needs a Databricks Access Connector resource with managed identity and Storage Blob Data Contributor on the metastore storage account. Without this, catalog operations fail. -4. **DBU pricing model** -- Costs are per DBU (Databricks Unit), not per VM. Different workload types (Jobs, SQL, All-Purpose) have different DBU rates. All-Purpose clusters are 2-3x more expensive than Jobs clusters. -5. **Cluster auto-termination** -- Default is 120 minutes. Set to 30 minutes for POC to reduce costs. Interactive clusters left running over weekends can be expensive. -6. **Spark version compatibility** -- Libraries pinned to specific Spark versions may break on runtime upgrades. Use LTS runtimes and test library compatibility. -7. **Secret management** -- Never hardcode secrets in notebooks. Use Databricks secret scopes backed by Azure Key Vault. -8. **Premium tier required for key features** -- Unity Catalog, RBAC, cluster policies, audit logs all require Premium tier. Standard tier is rarely sufficient. - -## Production Backlog Items - -- [ ] Enable VNet injection with no-public-IP for secure cluster connectivity -- [ ] Configure Unity Catalog with production metastore and access controls -- [ ] Set up cluster policies to control cost and compliance -- [ ] Enable audit logging to Log Analytics -- [ ] Configure IP access lists for workspace access control -- [ ] Implement CI/CD with Databricks Asset Bundles or Repos -- [ ] Set up automated job clusters (cheaper than interactive clusters) -- [ ] Configure disaster recovery with workspace replication -- [ ] Enable customer-managed keys for encryption at rest -- [ ] Implement data lineage tracking with Unity Catalog -- [ ] Set up cost monitoring and budget alerts per workspace +--- +service_namespace: Microsoft.Databricks/workspaces +display_name: Azure Databricks +--- + +# Azure Databricks +> Unified analytics platform for data engineering, data science, and machine learning built on Apache Spark with collaborative notebooks and Delta Lake. + +## When to Use + +- **Large-scale data processing** -- Spark-based ETL/ELT for petabyte-scale data +- **Machine learning** -- MLflow-based experiment tracking, model training, and deployment +- **Delta Lake** -- ACID transactions, schema enforcement, and time travel on data lakes +- **Real-time streaming** -- Structured Streaming for continuous data processing +- **Collaborative analytics** -- shared notebooks for data engineers, scientists, and analysts +- **Unity Catalog governance** -- centralized data cataloging, lineage, and access control + +Choose Databricks over Fabric when you need advanced Spark tuning, custom ML pipelines, multi-cloud portability, or have existing Databricks investments. Choose Fabric for simpler analytics with Power BI integration and T-SQL access. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Pricing tier | Premium | Required for Unity Catalog, RBAC; not significantly more expensive | +| Cluster type | Single-node | Smallest for development; no worker nodes | +| Node type | Standard_D4s_v5 | 4 vCPU, 16 GiB; good balance for POC | +| Auto-termination | 30 minutes | Prevent idle cluster costs | +| Runtime | Latest LTS | e.g., 14.3 LTS with Spark 3.5 | +| Unity Catalog | Enabled | Free with Premium tier; required for governance | +| Public network access | Disabled (unless user overrides) | Flag VNet injection as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.Databricks/workspaces@2024-05-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "premium" # Required for Unity Catalog + } + properties = { + managedResourceGroupId = "/subscriptions/${var.subscription_id}/resourceGroups/${var.resource_group_name}-databricks-managed" + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### VNet Injection + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.Databricks/workspaces@2024-05-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "premium" + } + properties = { + managedResourceGroupId = "/subscriptions/${var.subscription_id}/resourceGroups/${var.resource_group_name}-databricks-managed" + publicNetworkAccess = "Disabled" + requiredNsgRules = "NoAzureDatabricksRules" + parameters = { + customVirtualNetworkId = { + value = var.vnet_id + } + customPublicSubnetName = { + value = var.public_subnet_name + } + customPrivateSubnetName = { + value = var.private_subnet_name + } + enableNoPublicIp = { + value = true # Secure cluster connectivity + } + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### Unity Catalog Metastore + +```hcl +# Storage account for Unity Catalog metastore +resource "azapi_resource" "unity_storage" { + type = "Microsoft.Storage/storageAccounts@2023-05-01" + name = var.unity_storage_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "StorageV2" + sku = { + name = "Standard_LRS" + } + properties = { + isHnsEnabled = true # Hierarchical namespace (ADLS Gen2) + } + } + + tags = var.tags + + response_export_values = ["*"] +} + +resource "azapi_resource" "unity_container" { + type = "Microsoft.Storage/storageAccounts/blobServices/containers@2023-05-01" + name = "unity-catalog" + parent_id = "${azapi_resource.unity_storage.id}/blobServices/default" + + body = { + properties = { + publicAccess = "None" + } + } +} + +# Unity Catalog metastore (via Databricks provider) +resource "databricks_metastore" "this" { + name = "poc-metastore" + storage_root = "abfss://unity-catalog@${azapi_resource.unity_storage.name}.dfs.core.windows.net/" + force_destroy = true # POC only + owner = var.admin_group_name +} + +resource "databricks_metastore_assignment" "this" { + workspace_id = azapi_resource.this.output.properties.workspaceId + metastore_id = databricks_metastore.this.id + default_catalog_name = "main" +} +``` + +### RBAC Assignment + +```hcl +# Contributor on workspace (ARM-level management) +resource "azapi_resource" "dbw_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-contributor") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" + principalId = var.admin_identity_principal_id + } + } +} + +# Grant Databricks managed identity access to storage for Unity Catalog +resource "azapi_resource" "unity_blob_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.unity_storage.id}-blob-contributor") + parent_id = azapi_resource.unity_storage.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" + principalId = databricks_metastore.this.delta_sharing_organization_name # Access connector ID + } + } +} +``` + +**Note:** Databricks uses its own ACL system for data-plane access (workspace groups, Unity Catalog grants). ARM RBAC controls management-plane access only. + +### Private Endpoint + +Databricks uses **VNet injection** (see above) rather than traditional private endpoints. For additional frontend private endpoint access: + +```hcl +resource "azapi_resource" "databricks_pe" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.this.id + groupIds = ["databricks_ui_api"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "databricks_pe_dns" { + count = var.enable_private_endpoint && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.databricks_pe[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.azuredatabricks.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Databricks workspace') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Managed resource group name') +param managedResourceGroupName string = '${resourceGroup().name}-databricks-managed' + +@description('Tags to apply') +param tags object = {} + +resource workspace 'Microsoft.Databricks/workspaces@2024-05-01' = { + name: name + location: location + tags: tags + sku: { + name: 'premium' + } + properties: { + managedResourceGroupId: subscriptionResourceId('Microsoft.Resources/resourceGroups', managedResourceGroupName) + publicNetworkAccess: 'Disabled' // Unless told otherwise, disabled per governance policy + requiredNsgRules: 'AllRules' + } +} + +output id string = workspace.id +output name string = workspace.name +output url string = 'https://${workspace.properties.workspaceUrl}' +output workspaceId string = workspace.properties.workspaceId +``` + +### VNet Injection (Bicep) + +```bicep +@description('VNet ID') +param vnetId string + +@description('Public subnet name') +param publicSubnetName string + +@description('Private subnet name') +param privateSubnetName string + +resource workspace 'Microsoft.Databricks/workspaces@2024-05-01' = { + name: name + location: location + tags: tags + sku: { + name: 'premium' + } + properties: { + managedResourceGroupId: subscriptionResourceId('Microsoft.Resources/resourceGroups', managedResourceGroupName) + publicNetworkAccess: 'Disabled' + requiredNsgRules: 'NoAzureDatabricksRules' + parameters: { + customVirtualNetworkId: { + value: vnetId + } + customPublicSubnetName: { + value: publicSubnetName + } + customPrivateSubnetName: { + value: privateSubnetName + } + enableNoPublicIp: { + value: true + } + } + } +} +``` + +### RBAC Assignment + +No data-plane RBAC via ARM -- use Databricks workspace ACLs and Unity Catalog grants. + +## Application Code + +### Python — Databricks SDK (External) + +```python +from databricks.sdk import WorkspaceClient + +# Authenticate using Azure AD (DefaultAzureCredential) +w = WorkspaceClient( + host="https://adb-1234567890.1.azuredatabricks.net", + azure_workspace_resource_id="/subscriptions/.../resourceGroups/.../providers/Microsoft.Databricks/workspaces/...", +) + +# List clusters +for c in w.clusters.list(): + print(f"{c.cluster_name}: {c.state}") + +# Run a notebook job +from databricks.sdk.service.jobs import Task, NotebookTask + +run = w.jobs.submit( + run_name="my-etl-job", + tasks=[ + Task( + task_key="etl", + existing_cluster_id="0123-456789-abcdef", + notebook_task=NotebookTask( + notebook_path="/Repos/etl/transform", + base_parameters={"date": "2024-01-01"}, + ), + ) + ], +).result() +``` + +### Python — Notebook Code (Databricks Runtime) + +```python +# Runs inside a Databricks notebook +# Unity Catalog table access +df = spark.read.table("main.default.customers") + +# Transform with Delta Lake +from pyspark.sql.functions import col, current_timestamp + +df_processed = ( + df.filter(col("status") == "active") + .withColumn("processed_at", current_timestamp()) +) + +# Write to Unity Catalog table +df_processed.write.mode("overwrite").saveAsTable("main.default.active_customers") + +# Access Azure Blob Storage via Unity Catalog external location +df_external = spark.read.format("csv").load("abfss://data@mystorageaccount.dfs.core.windows.net/raw/") +``` + +### SQL — Databricks SQL + +```sql +-- Unity Catalog SQL queries +USE CATALOG main; +USE SCHEMA default; + +CREATE TABLE IF NOT EXISTS orders ( + order_id BIGINT GENERATED ALWAYS AS IDENTITY, + customer_id BIGINT, + total DECIMAL(10, 2), + created_at TIMESTAMP DEFAULT current_timestamp() +) +USING DELTA +TBLPROPERTIES ('delta.enableChangeDataFeed' = true); + +-- Time travel +SELECT * FROM orders VERSION AS OF 5; +SELECT * FROM orders TIMESTAMP AS OF '2024-01-01T00:00:00Z'; +``` + +## Common Pitfalls + +1. **Managed resource group conflicts** -- Databricks creates a managed resource group for VMs, disks, and NSGs. The name must not already exist. Use a predictable naming convention. +2. **VNet injection subnet sizing** -- Each cluster node uses one IP. Public and private subnets need /26 minimum (64 IPs) for small clusters, /22 for production. Under-sized subnets cause cluster launch failures. +3. **Unity Catalog access connector** -- Unity Catalog needs a Databricks Access Connector resource with managed identity and Storage Blob Data Contributor on the metastore storage account. Without this, catalog operations fail. +4. **DBU pricing model** -- Costs are per DBU (Databricks Unit), not per VM. Different workload types (Jobs, SQL, All-Purpose) have different DBU rates. All-Purpose clusters are 2-3x more expensive than Jobs clusters. +5. **Cluster auto-termination** -- Default is 120 minutes. Set to 30 minutes for POC to reduce costs. Interactive clusters left running over weekends can be expensive. +6. **Spark version compatibility** -- Libraries pinned to specific Spark versions may break on runtime upgrades. Use LTS runtimes and test library compatibility. +7. **Secret management** -- Never hardcode secrets in notebooks. Use Databricks secret scopes backed by Azure Key Vault. +8. **Premium tier required for key features** -- Unity Catalog, RBAC, cluster policies, audit logs all require Premium tier. Standard tier is rarely sufficient. + +## Production Backlog Items + +- [ ] Enable VNet injection with no-public-IP for secure cluster connectivity +- [ ] Configure Unity Catalog with production metastore and access controls +- [ ] Set up cluster policies to control cost and compliance +- [ ] Enable audit logging to Log Analytics +- [ ] Configure IP access lists for workspace access control +- [ ] Implement CI/CD with Databricks Asset Bundles or Repos +- [ ] Set up automated job clusters (cheaper than interactive clusters) +- [ ] Configure disaster recovery with workspace replication +- [ ] Enable customer-managed keys for encryption at rest +- [ ] Implement data lineage tracking with Unity Catalog +- [ ] Set up cost monitoring and budget alerts per workspace diff --git a/azext_prototype/knowledge/services/ddos-protection.md b/azext_prototype/knowledge/services/ddos-protection.md new file mode 100644 index 0000000..ba3b554 --- /dev/null +++ b/azext_prototype/knowledge/services/ddos-protection.md @@ -0,0 +1,237 @@ +--- +service_namespace: Microsoft.Network/ddosProtectionPlans +display_name: Azure DDoS Protection +--- + +# Azure DDoS Protection +> Always-on traffic monitoring and automatic DDoS attack mitigation for Azure public IP resources, providing L3/L4 volumetric, protocol, and resource-layer attack protection. + +## When to Use + +- **Public-facing workloads** -- any architecture with public IP addresses exposed to the internet +- **Compliance requirements** -- regulatory frameworks requiring DDoS protection (PCI-DSS, SOC 2) +- **Financial protection** -- DDoS Protection includes cost protection credits for scale-out during attacks +- **Advanced telemetry** -- attack analytics, flow logs, and rapid response support +- **Multi-resource protection** -- single plan protects all public IPs in associated VNets +- NOT suitable for: pure internal/private workloads (no public IPs), or cost-constrained POC where Azure DDoS Infrastructure Protection (free, default) is acceptable + +All Azure resources have free DDoS Infrastructure Protection. DDoS Protection (paid) adds adaptive tuning, attack analytics, cost protection, and Rapid Response support. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Tier | DDoS Protection | Free Infrastructure Protection for tight-budget POC | +| Association | VNet-level | Plan associates with VNets; protects all public IPs in those VNets | +| Alerts | Enabled | Alert on DDoS attack detection and mitigation | +| Diagnostic logs | Enabled | Flow logs and mitigation reports | +| Cost protection | Included | Credits for scale-out costs during attacks (Standard only) | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "ddos_plan" { + type = "Microsoft.Network/ddosProtectionPlans@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + tags = var.tags +} +``` + +### Associate DDoS Plan with VNet + +```hcl +# Associate the DDoS protection plan with a VNet +resource "azapi_update_resource" "vnet_ddos" { + type = "Microsoft.Network/virtualNetworks@2024-01-01" + resource_id = var.virtual_network_id + + body = { + properties = { + addressSpace = { + addressPrefixes = var.address_prefixes + } + enableDdosProtection = true + ddosProtectionPlan = { + id = azapi_resource.ddos_plan.id + } + } + } +} +``` + +### DDoS Protection Plan with Multiple VNets + +```hcl +resource "azapi_resource" "ddos_plan" { + type = "Microsoft.Network/ddosProtectionPlans@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + tags = var.tags +} + +# One plan can protect multiple VNets (even cross-subscription) +resource "azapi_update_resource" "vnet_ddos_assoc" { + for_each = var.virtual_network_ids + + type = "Microsoft.Network/virtualNetworks@2024-01-01" + resource_id = each.value + + body = { + properties = { + addressSpace = { + addressPrefixes = var.vnet_address_prefixes[each.key] + } + enableDdosProtection = true + ddosProtectionPlan = { + id = azapi_resource.ddos_plan.id + } + } + } +} +``` + +### Diagnostic Settings + +```hcl +# Enable diagnostic logging for DDoS-protected public IPs +resource "azapi_resource" "ddos_diagnostics" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "ddos-diagnostics" + parent_id = var.public_ip_id # Diagnostics are on the public IP, not the plan + + body = { + properties = { + workspaceId = var.log_analytics_workspace_id + logs = [ + { + categoryGroup = "allLogs" + enabled = true + retentionPolicy = { + days = 30 + enabled = true + } + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + retentionPolicy = { + days = 30 + enabled = true + } + } + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor for DDoS plan management +resource "azapi_resource" "ddos_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.ddos_plan.id}-${var.admin_principal_id}-network-contributor") + parent_id = azapi_resource.ddos_plan.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +DDoS Protection does not use private endpoints -- it is a network-level protection service that attaches to VNets and automatically protects all public IPs within those VNets. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the DDoS Protection Plan') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource ddosPlan 'Microsoft.Network/ddosProtectionPlans@2024-01-01' = { + name: name + location: location + tags: tags +} + +output id string = ddosPlan.id +``` + +### VNet Association + +```bicep +@description('VNet name to protect') +param vnetName string + +@description('VNet address prefixes') +param addressPrefixes array + +resource vnet 'Microsoft.Network/virtualNetworks@2024-01-01' existing = { + name: vnetName +} + +resource vnetDdos 'Microsoft.Network/virtualNetworks@2024-01-01' = { + name: vnetName + location: vnet.location + properties: { + addressSpace: { + addressPrefixes: addressPrefixes + } + enableDdosProtection: true + ddosProtectionPlan: { + id: ddosPlan.id + } + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Cost surprise | DDoS Protection Plan is ~$2,944/month flat fee | One plan covers up to 100 public IPs across VNets; share across subscriptions | +| Not associating with VNet | Plan exists but no resources are protected | Associate plan with each VNet containing public IPs | +| Confusing Infrastructure vs. Protection | Infrastructure Protection is basic and free; Protection is the paid plan | Infrastructure Protection is automatic; paid plan is needed for advanced features | +| Forgetting diagnostic logging on public IPs | No attack visibility or forensics | Enable diagnostics on each protected public IP, not on the plan | +| Protecting too many plans | Each plan is $2,944/month; only one is needed per tenant | Use a single plan associated with multiple VNets across subscriptions | +| No alert configuration | Attacks happen without notification | Configure Azure Monitor alerts on DDoS metrics for each public IP | +| Removing plan accidentally | All associated VNets lose protection immediately | Use resource locks on the DDoS plan | +| Not claiming cost protection | Scale-out costs during attack are not refunded automatically | File support ticket with attack logs to claim cost protection credits | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| DDoS Rapid Response | P1 | Enroll in DDoS Rapid Response for Microsoft-assisted mitigation during attacks | +| Attack analytics | P1 | Enable attack analytics for post-attack forensics and reporting | +| Metric alerts | P1 | Configure alerts on `UnderDDoSAttack`, `PacketsDroppedDDoS`, `BytesDroppedDDoS` | +| Cross-subscription sharing | P2 | Associate the single plan with VNets in other subscriptions to reduce cost | +| Flow logs | P2 | Enable DDoS mitigation flow logs for detailed traffic analysis | +| IP protection configuration | P3 | Review auto-tuned protection thresholds for each public IP | +| Resource lock | P1 | Apply CannotDelete lock on the DDoS plan to prevent accidental removal | +| Integration with SIEM | P2 | Forward DDoS logs to SIEM for security operations center visibility | +| Cost protection documentation | P2 | Document the cost protection claim process for operations team | +| Regular drills | P3 | Schedule DDoS simulation tests with approved testing partners | diff --git a/azext_prototype/knowledge/services/defender.md b/azext_prototype/knowledge/services/defender.md new file mode 100644 index 0000000..1646dff --- /dev/null +++ b/azext_prototype/knowledge/services/defender.md @@ -0,0 +1,294 @@ +--- +service_namespace: Microsoft.Security/pricings +display_name: Microsoft Defender for Cloud +--- + +# Microsoft Defender for Cloud +> Unified cloud security posture management (CSPM) and cloud workload protection platform (CWPP) providing security recommendations, threat detection, and vulnerability assessment across Azure, multi-cloud, and hybrid environments. + +## When to Use + +- Security posture assessment and hardening recommendations for Azure resources +- Threat protection for compute (VMs, containers, App Service), data (SQL, Storage), and identity +- Regulatory compliance dashboards (PCI DSS, SOC 2, ISO 27001, NIST) +- Vulnerability scanning for VMs, container images, and SQL databases +- Just-in-time VM access and adaptive application controls +- NOT suitable for: SIEM/incident management (use Microsoft Sentinel), identity governance (use Entra ID), or network traffic inspection (use Azure Firewall/NSGs) + +**Note**: Defender for Cloud has two tiers: Free (basic CSPM with security score and recommendations) and Enhanced (per-resource plans with advanced threat protection). Most Defender plans are subscription-level resources. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Tier | Free (Foundational CSPM) | Enhanced plans cost per-resource; enable selectively | +| Auto-provisioning | Disabled | Enable selectively for production | +| Security contacts | 1-2 team emails | For alert notifications | +| Continuous export | Disabled | Enable with Log Analytics for production | +| Secure score | Enabled (always on) | Monitor and improve over time | +| Defender plans | None (free tier) | Enable per-workload as needed | + +## Terraform Patterns + +### Security Contact Configuration + +```hcl +resource "azapi_resource" "security_contact" { + type = "Microsoft.Security/securityContacts@2023-12-01-preview" + name = "default" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + emails = var.security_email + phone = var.security_phone + isEnabled = true + notificationsByRole = { + state = "On" + roles = ["Owner", "ServiceAdmin"] + } + notificationsSources = [ + { + sourceType = "Alert" + minimalSeverity = "Medium" + }, + { + sourceType = "AttackPath" + minimalRiskLevel = "Critical" + } + ] + } + } +} +``` + +### Enable Defender Plans (Subscription Level) + +```hcl +# Defender for Servers +resource "azapi_resource" "defender_servers" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "VirtualMachines" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_servers ? "Standard" : "Free" + subPlan = "P1" # P1 or P2 + } + } +} + +# Defender for App Service +resource "azapi_resource" "defender_appservice" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "AppServices" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_appservice ? "Standard" : "Free" + } + } +} + +# Defender for Key Vault +resource "azapi_resource" "defender_keyvault" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "KeyVaults" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_keyvault ? "Standard" : "Free" + } + } +} + +# Defender for Storage +resource "azapi_resource" "defender_storage" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "StorageAccounts" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_storage ? "Standard" : "Free" + subPlan = "DefenderForStorageV2" + } + } +} + +# Defender for SQL +resource "azapi_resource" "defender_sql" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "SqlServers" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_sql ? "Standard" : "Free" + } + } +} + +# Defender for Containers +resource "azapi_resource" "defender_containers" { + type = "Microsoft.Security/pricings@2024-01-01" + name = "Containers" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + pricingTier = var.enable_defender_containers ? "Standard" : "Free" + } + } +} +``` + +### Auto-Provisioning Settings + +```hcl +resource "azapi_resource" "auto_provision_mma" { + type = "Microsoft.Security/autoProvisioningSettings@2017-08-01-preview" + name = "default" + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + autoProvision = var.enable_auto_provisioning ? "On" : "Off" + } + } +} +``` + +### Continuous Export to Log Analytics + +```hcl +resource "azapi_resource" "continuous_export" { + type = "Microsoft.Security/automations@2023-12-01-preview" + name = var.export_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + isEnabled = true + description = "Export Defender alerts and recommendations to Log Analytics" + scopes = [ + { + description = "Subscription scope" + scopePath = "/subscriptions/${var.subscription_id}" + } + ] + sources = [ + { + eventSource = "Alerts" + ruleSets = [] + }, + { + eventSource = "Assessments" + ruleSets = [] + } + ] + actions = [ + { + actionType = "Workspace" + workspaceResourceId = var.workspace_id + } + ] + } + } + + tags = var.tags +} +``` + +## Bicep Patterns + +### Security Contact Configuration + +```bicep +targetScope = 'subscription' + +param securityEmail string +param securityPhone string = '' + +resource securityContact 'Microsoft.Security/securityContacts@2023-12-01-preview' = { + name: 'default' + properties: { + emails: securityEmail + phone: securityPhone + isEnabled: true + notificationsByRole: { + state: 'On' + roles: ['Owner', 'ServiceAdmin'] + } + notificationsSources: [ + { + sourceType: 'Alert' + minimalSeverity: 'Medium' + } + ] + } +} +``` + +### Enable Defender Plans + +```bicep +targetScope = 'subscription' + +param enableDefenderServers bool = false +param enableDefenderAppService bool = false +param enableDefenderKeyVault bool = false + +resource defenderServers 'Microsoft.Security/pricings@2024-01-01' = { + name: 'VirtualMachines' + properties: { + pricingTier: enableDefenderServers ? 'Standard' : 'Free' + subPlan: 'P1' + } +} + +resource defenderAppService 'Microsoft.Security/pricings@2024-01-01' = { + name: 'AppServices' + properties: { + pricingTier: enableDefenderAppService ? 'Standard' : 'Free' + } +} + +resource defenderKeyVault 'Microsoft.Security/pricings@2024-01-01' = { + name: 'KeyVaults' + properties: { + pricingTier: enableDefenderKeyVault ? 'Standard' : 'Free' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Enabling all Defender plans at once | Unexpected costs; many plans charge per-resource per-month | Start with Free tier for POC; enable plans selectively | +| Not configuring security contacts | Critical alerts go unnoticed | Always set at least one email contact | +| Ignoring Secure Score recommendations | Security posture degrades over time | Review and address high-impact recommendations regularly | +| Auto-provisioning without planning | Agents deployed to all VMs, potential performance impact | Enable auto-provisioning selectively, test on non-production first | +| Confusing Defender for Cloud with Sentinel | Wrong tool for the job | Defender = prevention/detection per resource; Sentinel = SIEM/SOAR | +| Subscription-level resources in Terraform | Terraform state conflicts if multiple deployments target same subscription | Use a dedicated Terraform workspace for subscription-level Defender config | +| Not enabling continuous export | Alerts only visible in portal, not in Log Analytics | Enable continuous export for Sentinel integration and long-term retention | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Enable Defender plans | P1 | Enable Standard tier for production workloads (Servers, App Service, SQL, Storage, Key Vault) | +| Continuous export | P1 | Export alerts and recommendations to Log Analytics for Sentinel correlation | +| Just-in-time VM access | P2 | Enable JIT access to reduce VM attack surface | +| Adaptive application controls | P3 | Enable application allowlisting on VMs | +| Vulnerability assessment | P2 | Enable vulnerability scanning for VMs and container images | +| Regulatory compliance | P2 | Enable compliance dashboards for required standards (PCI DSS, SOC 2, etc.) | +| Workflow automation | P3 | Create Logic App workflows triggered by Defender recommendations | +| Multi-cloud connectors | P3 | Connect AWS/GCP accounts for unified security posture | +| Defender for DevOps | P3 | Enable DevOps security for pipeline and code scanning | +| Custom security policies | P2 | Create custom Azure Policy definitions for organization-specific requirements | diff --git a/azext_prototype/knowledge/services/devtest-schedule.md b/azext_prototype/knowledge/services/devtest-schedule.md new file mode 100644 index 0000000..01af8ec --- /dev/null +++ b/azext_prototype/knowledge/services/devtest-schedule.md @@ -0,0 +1,160 @@ +--- +service_namespace: Microsoft.DevTestLab/schedules +display_name: Auto-Shutdown Schedule +depends_on: + - Microsoft.Compute/virtualMachines +--- + +# Auto-Shutdown Schedule + +> Scheduled action (typically auto-shutdown) applied to Azure VMs to automatically stop compute at a specified time, reducing costs for non-production environments. + +## When to Use +- **Cost optimization** -- automatically shut down dev/test VMs outside business hours +- **POC environments** -- prevent forgotten VMs from running 24/7 +- **Compliance** -- enforce shutdown policies for non-production workloads +- Applies to individual VMs; for scale set schedules, use autoscale settings instead + +Despite the `DevTestLab` namespace, auto-shutdown schedules work on any Azure VM, not just DevTest Labs VMs. The resource is deployed as a child of the resource group but references a specific VM. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Name | `shutdown-computevm-{vmName}` | Must follow this exact naming convention | +| Task type | ComputeVmShutdownTask | Only supported task type | +| Daily recurrence | 19:00 | 7 PM local time | +| Time zone | User's time zone | e.g., `Eastern Standard Time` | +| Status | Enabled | Active by default | +| Notification | 30 minutes before | Email/webhook before shutdown | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "auto_shutdown" { + type = "Microsoft.DevTestLab/schedules@2018-09-15" + name = "shutdown-computevm-${var.vm_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + status = "Enabled" + taskType = "ComputeVmShutdownTask" + dailyRecurrence = { + time = var.shutdown_time # e.g., "1900" (24-hour format, no colon) + } + timeZoneId = var.time_zone # e.g., "Eastern Standard Time" + targetResourceId = var.vm_id + notificationSettings = { + status = "Enabled" + timeInMinutes = 30 + emailRecipient = var.notification_email + notificationLocale = "en" + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# DevTest Labs User role on the resource group for schedule management +resource "azapi_resource" "devtest_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.resource_group_id}-${var.principal_id}-devtest-user") + parent_id = var.resource_group_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/76283e04-6283-4c54-8f91-bcf1374a3c64" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('VM name (used in schedule resource name)') +param vmName string + +@description('VM resource ID') +param vmId string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Shutdown time in 24-hour format (e.g., 1900)') +param shutdownTime string = '1900' + +@description('Time zone ID') +param timeZoneId string = 'Eastern Standard Time' + +@description('Notification email') +param notificationEmail string = '' + +param tags object = {} + +resource autoShutdown 'Microsoft.DevTestLab/schedules@2018-09-15' = { + name: 'shutdown-computevm-${vmName}' + location: location + tags: tags + properties: { + status: 'Enabled' + taskType: 'ComputeVmShutdownTask' + dailyRecurrence: { + time: shutdownTime + } + timeZoneId: timeZoneId + targetResourceId: vmId + notificationSettings: { + status: notificationEmail != '' ? 'Enabled' : 'Disabled' + timeInMinutes: 30 + emailRecipient: notificationEmail + notificationLocale: 'en' + } + } +} + +output id string = autoShutdown.id +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Auto-shutdown operates at the VM level; applications running on the VM are stopped along with the VM. + +### C# +Infrastructure -- transparent to application code. Auto-shutdown operates at the VM level; applications running on the VM are stopped along with the VM. + +### Node.js +Infrastructure -- transparent to application code. Auto-shutdown operates at the VM level; applications running on the VM are stopped along with the VM. + +## Common Pitfalls + +1. **Name must follow exact convention** -- The resource name must be `shutdown-computevm-{vmName}` where `{vmName}` matches the VM name exactly. Any other name silently fails. +2. **Time format has no colon** -- The time is `"1900"` not `"19:00"`. Using a colon format causes deployment failure. +3. **Time zone ID must be Windows format** -- Use Windows time zone IDs (`Eastern Standard Time`, not `America/New_York`). Invalid IDs cause the schedule to never fire. +4. **Auto-shutdown does not auto-start** -- VMs are stopped but not deallocated by default. They still incur compute charges. Use the `deallocate` approach or Azure Automation for auto-start. +5. **Notification delay** -- The notification fires 30 minutes before shutdown by default. Users can delay shutdown from the notification email, but this is a one-time delay, not a permanent skip. +6. **Parent is resource group, not VM** -- Despite being conceptually tied to a VM, the schedule resource's parent is the resource group. The VM is referenced via `targetResourceId`. +7. **One schedule per VM** -- Each VM can have only one auto-shutdown schedule. Deploying a second overwrites the first. + +## Production Backlog Items + +- [ ] Configure auto-start schedules via Azure Automation for morning startup +- [ ] Adjust shutdown time based on actual usage patterns +- [ ] Add webhook notifications for integration with Slack/Teams +- [ ] Implement Azure Policy to enforce auto-shutdown on all dev/test VMs +- [ ] Configure different schedules for different environments (dev vs staging) +- [ ] Set up exception process for VMs that need to run 24/7 diff --git a/azext_prototype/knowledge/services/disk-encryption-set.md b/azext_prototype/knowledge/services/disk-encryption-set.md new file mode 100644 index 0000000..cfa41fa --- /dev/null +++ b/azext_prototype/knowledge/services/disk-encryption-set.md @@ -0,0 +1,260 @@ +--- +service_namespace: Microsoft.Compute/diskEncryptionSets +display_name: Disk Encryption Set +--- + +# Azure Disk Encryption Set +> Resource that binds Azure Managed Disks to a customer-managed key (CMK) in Key Vault or Managed HSM, enabling server-side encryption of OS and data disks with keys you control. + +## When to Use + +- Encrypting VM managed disks with customer-managed keys (CMK) instead of platform-managed keys +- Regulatory compliance requiring customer key control over data-at-rest encryption +- Double encryption (platform key + customer key) for defense-in-depth +- Confidential disk encryption for confidential VMs +- Centralizing encryption key management across multiple VMs and disks +- NOT suitable for: encrypting blobs/files in Storage (use Storage Account CMK directly), encrypting databases (use database-level TDE with CMK), or client-side encryption (use application-level encryption) + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Encryption type | EncryptionAtRestWithCustomerKey | Most common; platform + customer key also available | +| Key source | Key Vault | Managed HSM for FIPS 140-2 Level 3 | +| Key rotation | Manual | Enable auto-rotation for production | +| Identity | System-assigned | For accessing Key Vault | +| Federated client ID | None | Required for cross-tenant Key Vault access | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "disk_encryption_set" { + type = "Microsoft.Compute/diskEncryptionSets@2023-10-02" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + encryptionType = "EncryptionAtRestWithCustomerKey" + activeKey = { + keyUrl = var.key_vault_key_url # Full versioned or versionless Key Vault key URL + sourceVault = { + id = var.key_vault_id + } + } + rotationToLatestKeyVersionEnabled = true # Auto-rotate to latest key version + } + } + + tags = var.tags +} +``` + +### Key Vault Key (prerequisite) + +```hcl +resource "azapi_resource" "encryption_key" { + type = "Microsoft.KeyVault/vaults/keys@2023-07-01" + name = var.key_name + parent_id = var.key_vault_id + + body = { + properties = { + kty = "RSA" + keySize = 4096 + keyOps = ["wrapKey", "unwrapKey"] + } + } + + response_export_values = ["properties.keyUriWithVersion", "properties.keyUri"] +} +``` + +### RBAC Assignment (Key Vault Access) + +```hcl +# Grant DES identity Key Vault Crypto Service Encryption User +# This role allows the DES to wrap/unwrap keys for disk encryption +resource "azapi_resource" "des_key_vault_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.key_vault_id}${azapi_resource.disk_encryption_set.identity[0].principal_id}crypto-service-encryption") + parent_id = var.key_vault_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/e147488a-f6f5-4113-8e2d-b22465e65bf6" # Key Vault Crypto Service Encryption User + principalId = azapi_resource.disk_encryption_set.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Using DES with a Managed Disk + +```hcl +resource "azapi_resource" "managed_disk" { + type = "Microsoft.Compute/disks@2023-10-02" + name = var.disk_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Premium_LRS" + } + properties = { + diskSizeGB = var.disk_size_gb + creationData = { + createOption = "Empty" + } + encryption = { + diskEncryptionSetId = azapi_resource.disk_encryption_set.id + type = "EncryptionAtRestWithCustomerKey" + } + } + } + + tags = var.tags +} +``` + +### Double Encryption + +```hcl +resource "azapi_resource" "des_double_encryption" { + type = "Microsoft.Compute/diskEncryptionSets@2023-10-02" + name = "${var.name}-double" + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + encryptionType = "EncryptionAtRestWithPlatformAndCustomerKeys" + activeKey = { + keyUrl = var.key_vault_key_url + sourceVault = { + id = var.key_vault_id + } + } + rotationToLatestKeyVersionEnabled = true + } + } + + tags = var.tags +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param keyVaultId string +param keyVaultKeyUrl string +param tags object = {} + +resource diskEncryptionSet 'Microsoft.Compute/diskEncryptionSets@2023-10-02' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + encryptionType: 'EncryptionAtRestWithCustomerKey' + activeKey: { + keyUrl: keyVaultKeyUrl + sourceVault: { + id: keyVaultId + } + } + rotationToLatestKeyVersionEnabled: true + } +} + +output id string = diskEncryptionSet.id +output name string = diskEncryptionSet.name +output principalId string = diskEncryptionSet.identity.principalId +``` + +### RBAC Assignment + +```bicep +param keyVaultId string + +// Key Vault Crypto Service Encryption User for DES identity +resource cryptoServiceUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVaultId, diskEncryptionSet.identity.principalId, 'e147488a-f6f5-4113-8e2d-b22465e65bf6') + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'e147488a-f6f5-4113-8e2d-b22465e65bf6') + principalId: diskEncryptionSet.identity.principalId + principalType: 'ServicePrincipal' + } +} +``` + +### Using DES with Managed Disk + +```bicep +param diskName string +param diskSizeGB int = 128 +param diskEncryptionSetId string + +resource managedDisk 'Microsoft.Compute/disks@2023-10-02' = { + name: diskName + location: location + sku: { + name: 'Premium_LRS' + } + properties: { + diskSizeGB: diskSizeGB + creationData: { + createOption: 'Empty' + } + encryption: { + diskEncryptionSetId: diskEncryptionSetId + type: 'EncryptionAtRestWithCustomerKey' + } + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Not granting Key Vault Crypto Service Encryption User | DES cannot access the key; disk operations fail | Assign the role before creating disks that reference the DES | +| Using access policies instead of RBAC on Key Vault | Inconsistent with governance policy; harder to manage | Use RBAC authorization on Key Vault, not legacy access policies | +| Key Vault soft delete disabled | Key Vault with encryption keys must have soft delete and purge protection | Enable both before creating the DES | +| Key deleted or expired | All disks encrypted with the DES become inaccessible | Enable key auto-rotation and purge protection | +| DES and Key Vault in different regions | Cross-region latency; some scenarios not supported | Keep DES, Key Vault, and disks in the same region | +| Using versioned key URL without auto-rotation | Disks stuck on old key version after rotation | Use versionless key URL with `rotationToLatestKeyVersionEnabled = true` | +| Circular dependency with Key Vault | DES needs Key Vault, but Key Vault may need DES identity for access policy | Create DES first, then grant RBAC, then create disks | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Key auto-rotation | P1 | Enable `rotationToLatestKeyVersionEnabled` and use versionless key URLs | +| Purge protection on Key Vault | P1 | Ensure Key Vault has purge protection enabled to prevent accidental key deletion | +| Double encryption | P2 | Evaluate EncryptionAtRestWithPlatformAndCustomerKeys for defense-in-depth | +| Managed HSM backend | P3 | Switch from Key Vault to Managed HSM for FIPS 140-2 Level 3 compliance | +| Key rotation monitoring | P2 | Set up alerts for key expiration and rotation failures | +| Cross-region DR | P3 | Plan key replication strategy for disaster recovery | +| Confidential disk encryption | P3 | Evaluate ConfidentialVmEncryptedWithCustomerKey for confidential computing | +| Audit key usage | P2 | Enable Key Vault diagnostic logging to track key operations | diff --git a/azext_prototype/knowledge/services/disk.md b/azext_prototype/knowledge/services/disk.md new file mode 100644 index 0000000..620070e --- /dev/null +++ b/azext_prototype/knowledge/services/disk.md @@ -0,0 +1,155 @@ +--- +service_namespace: Microsoft.Compute/disks +display_name: Azure Managed Disk +--- + +# Azure Managed Disk + +> Block-level storage volume managed by Azure, used as OS disks and data disks for Virtual Machines with built-in redundancy, encryption, and snapshot capabilities. + +## When to Use +- **VM OS disk** -- every Azure VM requires an OS disk (automatically created with the VM) +- **VM data disks** -- additional persistent storage for databases, file shares, application data +- **Standalone snapshots** -- create managed disks from snapshots for backup/restore +- **Disk-based migration** -- import VHDs from on-premises as managed disks +- **Shared disks** -- multi-attach scenarios for Windows Server Failover Clustering + +Managed disks are typically created alongside VMs, but standalone disk resources are used for pre-provisioning, cross-VM attachment, or creating from snapshots/images. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard_LRS | Lowest cost; HDD-based, sufficient for POC | +| SKU (alternative) | StandardSSD_LRS | Better IOPS than HDD; recommended for most POC workloads | +| Size | 32 GB (P4/E4/S4) | Minimum useful size; disks smaller than 32 GB may have throttled IOPS | +| Encryption | Platform-managed keys | Default SSE; CMK for compliance | +| OS disk type | From image | Created with VM from marketplace image | +| Bursting | Disabled | Enable on-demand for P20+ Premium SSD | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "data_disk" { + type = "Microsoft.Compute/disks@2024-03-02" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "StandardSSD_LRS" # or "Premium_LRS", "Standard_LRS", "UltraSSD_LRS" + } + properties = { + diskSizeGB = var.disk_size_gb # e.g., 64 + creationData = { + createOption = "Empty" # or "FromImage", "Copy", "Upload" + } + encryption = { + type = "EncryptionAtRestWithPlatformKey" # Default SSE + } + } + zones = var.availability_zone != null ? [var.availability_zone] : null + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### RBAC Assignment + +```hcl +# Disk Backup Reader -- for backup scenarios +resource "azapi_resource" "disk_backup_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.data_disk.id}-${var.principal_id}-disk-backup") + parent_id = azapi_resource.data_disk.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/3e5e47e6-65f7-47ef-90b5-e5dd4d455f24" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Disk name') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Disk size in GB') +param diskSizeGB int = 64 + +@description('Disk SKU') +@allowed(['Standard_LRS', 'StandardSSD_LRS', 'Premium_LRS', 'UltraSSD_LRS', 'PremiumV2_LRS', 'StandardSSD_ZRS', 'Premium_ZRS']) +param skuName string = 'StandardSSD_LRS' + +param tags object = {} + +resource disk 'Microsoft.Compute/disks@2024-03-02' = { + name: name + location: location + tags: tags + sku: { + name: skuName + } + properties: { + diskSizeGB: diskSizeGB + creationData: { + createOption: 'Empty' + } + encryption: { + type: 'EncryptionAtRestWithPlatformKey' + } + } +} + +output id string = disk.id +output name string = disk.name +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Managed disks appear as block devices (`/dev/sdc`, `D:\`) to the OS; applications use standard file I/O operations. + +### C# +Infrastructure -- transparent to application code. Managed disks appear as block devices to the OS; applications use standard `System.IO` file operations. + +### Node.js +Infrastructure -- transparent to application code. Managed disks appear as block devices to the OS; applications use standard `fs` module operations. + +## Common Pitfalls + +1. **Disk SKU determines IOPS/throughput** -- Standard_LRS (HDD) has 500 IOPS max. StandardSSD_LRS has 500-6000 IOPS depending on size. Premium_LRS has 120-20000 IOPS. Under-provisioned disks cause I/O bottlenecks. +2. **Disk size determines performance tier** -- Larger disks within the same SKU get higher IOPS/throughput baselines. A 32 GB Premium SSD (P4) gets 120 IOPS; a 256 GB (P15) gets 1100 IOPS. +3. **Zone must match VM** -- A disk in zone 1 cannot be attached to a VM in zone 2. Always deploy disks in the same zone as the target VM. +4. **Cannot resize down** -- Disk size can only be increased, never decreased. Over-provisioning wastes cost permanently. +5. **Detach before deleting** -- Deleting a disk attached to a running VM fails. Stop/deallocate the VM and detach the disk first. +6. **UltraSSD requires opt-in** -- Ultra disks require enabling `UltraSSDEnabled` on the VM and are only available in specific regions and zones. +7. **Encryption at host vs SSE** -- `EncryptionAtRestWithPlatformKey` (SSE) encrypts data at rest on the storage backend. For end-to-end encryption (including temp disks and caches), enable encryption at host on the VM. +8. **Snapshot cost** -- Snapshots are billed based on used size, not provisioned size. Frequent snapshots of large disks can accumulate significant storage costs. + +## Production Backlog Items + +- [ ] Upgrade to Premium SSD or Premium SSD v2 for production IOPS requirements +- [ ] Enable customer-managed key (CMK) encryption via Key Vault +- [ ] Configure Azure Backup with appropriate retention policies +- [ ] Enable encryption at host on VMs for end-to-end encryption +- [ ] Implement snapshot-based backup strategy with lifecycle management +- [ ] Enable zone-redundant storage (ZRS) SKU for cross-zone resilience +- [ ] Right-size disk SKU and size based on observed I/O patterns +- [ ] Plan disk bursting strategy for intermittent high-I/O workloads diff --git a/azext_prototype/knowledge/services/dns-zone-a-record.md b/azext_prototype/knowledge/services/dns-zone-a-record.md new file mode 100644 index 0000000..4824ea9 --- /dev/null +++ b/azext_prototype/knowledge/services/dns-zone-a-record.md @@ -0,0 +1,119 @@ +--- +service_namespace: Microsoft.Network/dnsZones/A +display_name: DNS Zone A Record +depends_on: + - Microsoft.Network/dnsZones +--- + +# DNS Zone A Record + +> An A (Address) record in a public DNS zone that maps a hostname to one or more IPv4 addresses. + +## When to Use +- Map a custom domain to an Azure resource's public IP address +- Point root domain (apex) to an Azure service (use alias record for dynamic IPs) +- Create subdomains pointing to specific IP addresses +- Required for custom domain verification and routing + +## POC Defaults +- **TTL**: 300 seconds (5 minutes — short for POC iteration) +- **Records**: Single IPv4 address +- **Alias**: Use targetResource for Azure resources with dynamic IPs + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "dns_a_record" { + type = "Microsoft.Network/dnsZones/A@2023-07-01-preview" + name = var.record_name + parent_id = azapi_resource.dns_zone.id + + body = { + properties = { + TTL = 300 + ARecords = [ + { ipv4Address = var.target_ip } + ] + } + } +} + +# Alias record pointing to an Azure resource +resource "azapi_resource" "dns_a_alias" { + type = "Microsoft.Network/dnsZones/A@2023-07-01-preview" + name = var.record_name + parent_id = azapi_resource.dns_zone.id + + body = { + properties = { + TTL = 300 + targetResource = { + id = azapi_resource.public_ip.id + } + } + } +} +``` + +### RBAC Assignment +```hcl +# DNS Zone Contributor role allows managing records within a zone. +# Scoped at the zone level for least privilege. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param recordName string +param targetIp string +param ttl int = 300 + +resource aRecord 'Microsoft.Network/dnsZones/A@2023-07-01-preview' = { + parent: dnsZone + name: recordName + properties: { + TTL: ttl + ARecords: [ + { ipv4Address: targetIp } + ] + } +} + +// Alias record for Azure resource +resource aAlias 'Microsoft.Network/dnsZones/A@2023-07-01-preview' = { + parent: dnsZone + name: recordName + properties: { + TTL: ttl + targetResource: { + id: publicIp.id + } + } +} +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **Alias vs static**: Use alias records (`targetResource`) for Azure resources with dynamic IPs (public IPs, Front Door, Traffic Manager). Static A records break when IPs change. +- **Apex record limitations**: CNAME records can't be used at the zone apex. Use A alias records to point the root domain to Azure resources. +- **TTL caching**: DNS clients cache records for the TTL duration. A 3600-second TTL means changes take up to 1 hour to propagate. Use short TTLs during POC. +- **Cannot mix alias and ARecords**: A record set is either alias-based (`targetResource`) or static (`ARecords`), not both. The API rejects mixed configurations. +- **Name '@' for apex**: Use `@` as the record name to create an apex (root) record. + +## Production Backlog Items +- Increase TTL to 3600 seconds for reduced DNS query load +- Geographic or latency-based routing via Traffic Manager alias records +- DNSSEC configuration for DNS response integrity +- Automated DNS record lifecycle management diff --git a/azext_prototype/knowledge/services/dns-zone-cname-record.md b/azext_prototype/knowledge/services/dns-zone-cname-record.md new file mode 100644 index 0000000..0d4ad9a --- /dev/null +++ b/azext_prototype/knowledge/services/dns-zone-cname-record.md @@ -0,0 +1,107 @@ +--- +service_namespace: Microsoft.Network/dnsZones/CNAME +display_name: DNS Zone CNAME Record +depends_on: + - Microsoft.Network/dnsZones +--- + +# DNS Zone CNAME Record + +> A CNAME (Canonical Name) record in a public DNS zone that maps an alias hostname to another domain name (the canonical name). + +## When to Use +- Map subdomains to Azure service FQDNs (e.g., `www` to `myapp.azurewebsites.net`) +- Create vanity URLs pointing to Azure-managed endpoints +- Custom domain verification for App Service, Front Door, or CDN +- NOT usable at the zone apex (use an A alias record instead) + +## POC Defaults +- **TTL**: 300 seconds (5 minutes — short for POC iteration) +- **CNAME**: Points to the Azure service FQDN + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "dns_cname_record" { + type = "Microsoft.Network/dnsZones/CNAME@2023-07-01-preview" + name = var.record_name + parent_id = azapi_resource.dns_zone.id + + body = { + properties = { + TTL = 300 + CNAMERecord = { + cname = var.target_fqdn + } + } + } +} + +# Alias CNAME pointing to an Azure resource +resource "azapi_resource" "dns_cname_alias" { + type = "Microsoft.Network/dnsZones/CNAME@2023-07-01-preview" + name = var.record_name + parent_id = azapi_resource.dns_zone.id + + body = { + properties = { + TTL = 300 + targetResource = { + id = azapi_resource.cdn_endpoint.id + } + } + } +} +``` + +### RBAC Assignment +```hcl +# DNS Zone Contributor role allows managing records within a zone. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param recordName string +param targetFqdn string +param ttl int = 300 + +resource cnameRecord 'Microsoft.Network/dnsZones/CNAME@2023-07-01-preview' = { + parent: dnsZone + name: recordName + properties: { + TTL: ttl + CNAMERecord: { + cname: targetFqdn + } + } +} + +output fqdn string = '${recordName}.${dnsZone.name}' +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **Cannot use at zone apex**: CNAME records are prohibited at the zone root (e.g., `contoso.com`). Use an A alias record for apex domains. +- **Only one CNAME per name**: A CNAME record set can only contain a single record. Multiple CNAMEs for the same name are invalid per DNS RFC. +- **Cannot coexist with other record types**: If a CNAME exists for a name, no other record types (A, MX, TXT) can exist for that same name. +- **Custom domain validation**: Services like App Service require a TXT or CNAME verification record before accepting the custom domain binding. Create the verification record first. +- **Trailing dot**: Azure DNS normalizes FQDNs. You don't need to include the trailing dot in the `cname` value, but it's accepted. + +## Production Backlog Items +- Increase TTL to 3600 seconds for reduced DNS query load +- Custom domain SSL certificate automation (App Service managed certificates) +- CNAME flattening considerations if migrating to apex records +- DNS record inventory and drift detection diff --git a/azext_prototype/knowledge/services/dns-zones.md b/azext_prototype/knowledge/services/dns-zones.md new file mode 100644 index 0000000..eaf7f48 --- /dev/null +++ b/azext_prototype/knowledge/services/dns-zones.md @@ -0,0 +1,292 @@ +--- +service_namespace: Microsoft.Network/dnsZones +display_name: Azure DNS Zones +--- + +# Azure DNS Zones +> Managed DNS hosting service for both public domains and private name resolution within Azure Virtual Networks, providing high availability and fast DNS queries using Azure's global anycast network. + +## When to Use + +- **Private DNS zones** -- name resolution for Azure resources within VNets (e.g., `privatelink.blob.core.windows.net` for private endpoints) +- **Public DNS zones** -- host public domain DNS records (A, AAAA, CNAME, MX, TXT, SRV, etc.) +- **Private endpoint DNS** -- every private endpoint requires a corresponding `privatelink.*` private DNS zone for FQDN resolution +- **Custom domain names** -- map custom domains to Azure services (App Service, Front Door, etc.) +- **Split-horizon DNS** -- different resolution for the same domain from inside vs. outside the VNet + +Private DNS zones are the most common use in POC architectures, primarily to support private endpoint name resolution. Public DNS zones are used when the POC needs a custom domain. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Zone type | Private | For private endpoint DNS resolution | +| Location | Global | DNS zones are always global resources | +| Registration enabled | false | Auto-registration is for VM DNS records; not needed for private endpoints | +| VNet links | One per VNet | Link to all VNets needing resolution | + +## Terraform Patterns + +### Private DNS Zone + +```hcl +resource "azapi_resource" "private_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2024-06-01" + name = var.zone_name # e.g., "privatelink.blob.core.windows.net" + location = "global" # Private DNS zones are always global + parent_id = var.resource_group_id + + tags = var.tags +} +``` + +### VNet Link + +```hcl +resource "azapi_resource" "dns_vnet_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2024-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false # true only for VM auto-registration scenarios + } + } + + tags = var.tags +} +``` + +### Public DNS Zone + +```hcl +resource "azapi_resource" "public_dns_zone" { + type = "Microsoft.Network/dnsZones@2023-07-01-preview" + name = var.domain_name # e.g., "contoso.com" + location = "global" + parent_id = var.resource_group_id + + tags = var.tags + + response_export_values = ["properties.nameServers"] +} + +# A record +resource "azapi_resource" "a_record" { + type = "Microsoft.Network/dnsZones/A@2023-07-01-preview" + name = var.record_name # e.g., "www" + parent_id = azapi_resource.public_dns_zone.id + + body = { + properties = { + TTL = 300 + ARecords = [ + { + ipv4Address = var.target_ip + } + ] + } + } +} + +# CNAME record +resource "azapi_resource" "cname_record" { + type = "Microsoft.Network/dnsZones/CNAME@2023-07-01-preview" + name = var.cname_name # e.g., "api" + parent_id = azapi_resource.public_dns_zone.id + + body = { + properties = { + TTL = 300 + CNAMERecord = { + cname = var.target_fqdn # e.g., "myapp.azurewebsites.net" + } + } + } +} +``` + +### Private DNS Zone Record (Manual) + +```hcl +# Usually records are auto-created by private endpoint DNS zone groups. +# Manual A records are needed for custom private DNS scenarios. +resource "azapi_resource" "private_a_record" { + type = "Microsoft.Network/privateDnsZones/A@2024-06-01" + name = var.record_name + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + ttl = 300 + aRecords = [ + { + ipv4Address = var.private_ip + } + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# Private DNS Zone Contributor -- manage records in private DNS zones +resource "azapi_resource" "dns_zone_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.private_dns_zone.id}${var.managed_identity_principal_id}dns-contributor") + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b12aa53e-6015-4669-85d0-8515ebb3ae7f" # Private DNS Zone Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# DNS Zone Contributor (public zones) +resource "azapi_resource" "public_dns_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.public_dns_zone.id}${var.managed_identity_principal_id}public-dns-contributor") + parent_id = azapi_resource.public_dns_zone.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/befefa01-2a29-4197-83a8-272ff33ce314" # DNS Zone Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Private DNS Zone with VNet Link + +```bicep +@description('Private DNS zone name (e.g., privatelink.blob.core.windows.net)') +param zoneName string + +@description('VNet resource ID to link') +param vnetId string + +@description('VNet name for the link resource name') +param vnetName string + +@description('Tags to apply') +param tags object = {} + +resource privateDnsZone 'Microsoft.Network/privateDnsZones@2024-06-01' = { + name: zoneName + location: 'global' + tags: tags +} + +resource vnetLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2024-06-01' = { + parent: privateDnsZone + name: 'link-${vnetName}' + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } + tags: tags +} + +output zoneId string = privateDnsZone.id +output zoneName string = privateDnsZone.name +``` + +### Public DNS Zone + +```bicep +@description('Domain name for the public DNS zone') +param domainName string + +@description('Tags to apply') +param tags object = {} + +resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = { + name: domainName + location: 'global' + tags: tags +} + +output id string = dnsZone.id +output nameServers array = dnsZone.properties.nameServers +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity') +param principalId string + +// Private DNS Zone Contributor +resource dnsZoneContributorRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(privateDnsZone.id, principalId, 'b12aa53e-6015-4669-85d0-8515ebb3ae7f') + scope: privateDnsZone + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b12aa53e-6015-4669-85d0-8515ebb3ae7f') // Private DNS Zone Contributor + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Private DNS Zone Names + +| Service | Private DNS Zone | +|---------|-----------------| +| Storage (Blob) | `privatelink.blob.core.windows.net` | +| Storage (File) | `privatelink.file.core.windows.net` | +| Storage (Queue) | `privatelink.queue.core.windows.net` | +| Storage (Table) | `privatelink.table.core.windows.net` | +| Key Vault | `privatelink.vaultcore.azure.net` | +| SQL Database | `privatelink.database.windows.net` | +| PostgreSQL Flexible | `privatelink.postgres.database.azure.com` | +| MySQL Flexible | `privatelink.mysql.database.azure.com` | +| Cosmos DB | `privatelink.documents.azure.com` | +| App Service / Functions | `privatelink.azurewebsites.net` | +| Container Registry | `privatelink.azurecr.io` | +| Redis Cache | `privatelink.redis.cache.windows.net` | +| Event Hubs / Service Bus | `privatelink.servicebus.windows.net` | +| SignalR | `privatelink.service.signalr.net` | +| Azure OpenAI | `privatelink.openai.azure.com` | +| Cognitive Services | `privatelink.cognitiveservices.azure.com` | +| Azure ML | `privatelink.api.azureml.ms` | +| Azure Search | `privatelink.search.windows.net` | + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Missing VNet link | DNS queries from the VNet do not resolve private endpoint records | Create `virtualNetworkLinks` for every VNet that needs resolution | +| `registrationEnabled = true` on PE zone | Auto-registers VM records into the zone, polluting private endpoint DNS | Set `registrationEnabled = false` for `privatelink.*` zones | +| Duplicate DNS zones | Multiple zones for the same name cause resolution conflicts | Centralize private DNS zones in a shared resource group; link to all VNets | +| Wrong zone name | Private endpoint DNS records not resolved | Use exact `privatelink.*` zone names from the reference table | +| Public DNS zone without NS delegation | External clients cannot resolve records | Update domain registrar NS records to point to Azure DNS name servers | +| TTL too high during migration | DNS changes take too long to propagate | Use low TTL (60-300s) during migration; increase after stabilization | +| Not linking hub VNet | Spoke VNets using hub DNS forwarder cannot resolve private endpoints | Link DNS zones to both hub and spoke VNets | + +## Production Backlog Items + +- [ ] Centralize private DNS zones in a shared networking resource group or subscription +- [ ] Link DNS zones to all VNets (hub and spokes) that need resolution +- [ ] Configure on-premises DNS forwarding for hybrid scenarios +- [ ] Set up monitoring alerts for DNS query volume and resolution failures +- [ ] Implement Azure Policy to enforce private DNS zone creation with private endpoints +- [ ] Review and consolidate duplicate DNS zones across resource groups +- [ ] Document DNS architecture and zone-to-service mapping +- [ ] Configure DNS zone diagnostic logging diff --git a/azext_prototype/knowledge/services/event-grid-subscription.md b/azext_prototype/knowledge/services/event-grid-subscription.md new file mode 100644 index 0000000..c328707 --- /dev/null +++ b/azext_prototype/knowledge/services/event-grid-subscription.md @@ -0,0 +1,192 @@ +--- +service_namespace: Microsoft.EventGrid/topics/eventSubscriptions +display_name: Event Grid Subscription +depends_on: + - Microsoft.EventGrid/topics +--- + +# Event Grid Subscription + +> Routes events from an Event Grid topic (custom or system) to a destination handler such as a webhook, Azure Function, Service Bus queue, Storage queue, or Event Hub. + +## When to Use +- Deliver events from custom topics or system topics to subscribers +- Filter events by type, subject prefix/suffix, or advanced filters +- Fan out events to multiple destinations with separate subscriptions +- Configure retry policies and dead-lettering for reliable delivery +- Every event-driven workflow needs at least one subscription + +## POC Defaults +- **Destination**: Webhook or Azure Function +- **Event delivery schema**: EventGridSchema (default) +- **Max delivery attempts**: 30 +- **Event TTL**: 1440 minutes (24 hours) +- **Subject filter**: None (receive all events) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "eg_subscription" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = var.subscription_name + parent_id = azapi_resource.eg_topic.id + + body = { + properties = { + destination = { + endpointType = "WebHook" + properties = { + endpointUrl = var.webhook_url + } + } + filter = { + includedEventTypes = var.event_types + subjectBeginsWith = var.subject_prefix + subjectEndsWith = var.subject_suffix + } + retryPolicy = { + maxDeliveryAttempts = 30 + eventTimeToLiveInMinutes = 1440 + } + } + } +} + +# Azure Function destination +resource "azapi_resource" "eg_subscription_func" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = var.subscription_name + parent_id = azapi_resource.eg_topic.id + + body = { + properties = { + destination = { + endpointType = "AzureFunction" + properties = { + resourceId = "${azapi_resource.function_app.id}/functions/${var.function_name}" + } + } + filter = { + includedEventTypes = var.event_types + } + } + } +} +``` + +### RBAC Assignment +```hcl +# EventGrid EventSubscription Contributor role allows creating subscriptions. +# The topic owner or Contributor can also manage subscriptions. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param subscriptionName string +param webhookUrl string +param eventTypes array = [] + +resource eventSubscription 'Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview' = { + parent: eventGridTopic + name: subscriptionName + properties: { + destination: { + endpointType: 'WebHook' + properties: { + endpointUrl: webhookUrl + } + } + filter: { + includedEventTypes: !empty(eventTypes) ? eventTypes : null + } + retryPolicy: { + maxDeliveryAttempts: 30 + eventTimeToLiveInMinutes: 1440 + } + } +} +``` + +## Application Code + +### Python +```python +# Event Grid delivers events to your handler. For webhook destinations: +from flask import Flask, request, jsonify + +app = Flask(__name__) + +@app.route("/events", methods=["POST"]) +def handle_events(): + events = request.get_json() + for event in events: + # Handle validation handshake + if event.get("eventType") == "Microsoft.EventGrid.SubscriptionValidationEvent": + validation_code = event["data"]["validationCode"] + return jsonify({"validationResponse": validation_code}) + # Handle actual events + print(f"Event: {event['eventType']}, Subject: {event['subject']}") + return "", 200 +``` + +### C# +```csharp +using Azure.Messaging.EventGrid; +using Microsoft.AspNetCore.Mvc; + +[ApiController] +[Route("events")] +public class EventGridController : ControllerBase +{ + [HttpPost] + public IActionResult HandleEvents([FromBody] EventGridEvent[] events) + { + foreach (var ev in events) + { + if (ev.EventType == "Microsoft.EventGrid.SubscriptionValidationEvent") + { + var data = ev.Data.ToObjectFromJson(); + return Ok(new { validationResponse = data.ValidationCode }); + } + _logger.LogInformation($"Event: {ev.EventType}, Subject: {ev.Subject}"); + } + return Ok(); + } +} +``` + +### Node.js +```typescript +import express from "express"; + +const app = express(); +app.use(express.json()); + +app.post("/events", (req, res) => { + const events = req.body; + for (const event of events) { + if (event.eventType === "Microsoft.EventGrid.SubscriptionValidationEvent") { + return res.json({ validationResponse: event.data.validationCode }); + } + console.log(`Event: ${event.eventType}, Subject: ${event.subject}`); + } + res.sendStatus(200); +}); +``` + +## Common Pitfalls +- **Webhook validation required**: When creating a webhook subscription, Event Grid sends a validation event. The endpoint must respond with the validation code or creation fails. +- **HTTPS required for webhooks**: Webhook endpoints must use HTTPS. HTTP endpoints are rejected. +- **Filter is inclusive**: `includedEventTypes` is an allowlist. An empty array means all event types. Omitting it also means all types. +- **Dead-letter requires storage**: Dead-letter destinations need a blob storage container. Without dead-lettering, failed events are dropped after max retry attempts. +- **System topic subscriptions**: For system topics, the parent resource type is `Microsoft.EventGrid/systemTopics/eventSubscriptions`, not `topics/eventSubscriptions`. + +## Production Backlog Items +- Dead-letter destination for failed event delivery +- Advanced filters for fine-grained event routing +- Managed identity authentication for delivery endpoints +- CloudEvents v1.0 schema for interoperability +- Event delivery metrics monitoring and alerting diff --git a/azext_prototype/knowledge/services/event-grid-system-topic.md b/azext_prototype/knowledge/services/event-grid-system-topic.md new file mode 100644 index 0000000..dd8e4ed --- /dev/null +++ b/azext_prototype/knowledge/services/event-grid-system-topic.md @@ -0,0 +1,143 @@ +--- +service_namespace: Microsoft.EventGrid/systemTopics +display_name: Event Grid System Topic +--- + +# Event Grid System Topic + +> A managed topic that represents events published by Azure services (Storage, Resource Groups, IoT Hub, etc.). System topics are automatically available for supported Azure resources. + +## When to Use +- React to Azure service events (blob created, resource modified, IoT device telemetry) +- Trigger Azure Functions, Logic Apps, or webhooks from Azure resource lifecycle events +- Storage events: blob created, blob deleted (common for data processing pipelines) +- Resource group events: resource write success/failure (infrastructure automation) +- Only one system topic per source per region per subscription + +## POC Defaults +- **Topic type**: Depends on source (e.g., `Microsoft.Storage.StorageAccounts`, `Microsoft.Resources.ResourceGroups`) +- **Location**: Must match the source resource's location +- **Identity**: System-assigned managed identity (for dead-letter and delivery auth) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "eg_system_topic" { + type = "Microsoft.EventGrid/systemTopics@2024-06-01-preview" + name = var.system_topic_name + parent_id = "/subscriptions/${var.subscription_id}/resourceGroups/${var.resource_group_name}" + location = var.location + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + source = azapi_resource.storage_account.id + topicType = "Microsoft.Storage.StorageAccounts" + } + } +} +``` + +### RBAC Assignment +```hcl +# EventGrid Contributor role allows managing system topics. +# The system topic's managed identity needs roles on delivery targets +# (e.g., Storage Blob Data Contributor for dead-letter container). +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param systemTopicName string +param location string +param sourceResourceId string + +resource systemTopic 'Microsoft.EventGrid/systemTopics@2024-06-01-preview' = { + name: systemTopicName + location: location + identity: { + type: 'SystemAssigned' + } + properties: { + source: sourceResourceId + topicType: 'Microsoft.Storage.StorageAccounts' + } +} + +output systemTopicId string = systemTopic.id +output systemTopicName string = systemTopic.name +``` + +## Application Code + +### Python +```python +# System topics emit events to subscriptions. The subscriber (e.g., Azure Function) handles events: +import azure.functions as func +import json + +def main(event: func.EventGridEvent): + data = event.get_json() + print(f"Event type: {event.event_type}") + print(f"Subject: {event.subject}") + # For storage events: data["url"], data["contentType"], data["contentLength"] + if event.event_type == "Microsoft.Storage.BlobCreated": + blob_url = data["url"] + print(f"New blob: {blob_url}") +``` + +### C# +```csharp +using Azure.Messaging.EventGrid; +using Microsoft.Azure.Functions.Worker; + +[Function("HandleStorageEvent")] +public async Task Run( + [EventGridTrigger] EventGridEvent eventGridEvent) +{ + _logger.LogInformation($"Event type: {eventGridEvent.EventType}"); + _logger.LogInformation($"Subject: {eventGridEvent.Subject}"); + + if (eventGridEvent.EventType == "Microsoft.Storage.BlobCreated") + { + var data = eventGridEvent.Data.ToObjectFromJson(); + _logger.LogInformation($"New blob: {data.Url}"); + } +} +``` + +### Node.js +```typescript +import { EventGridEvent } from "@azure/eventgrid"; +import { InvocationContext } from "@azure/functions"; + +export async function handleStorageEvent( + event: EventGridEvent, context: InvocationContext +): Promise { + context.log(`Event type: ${event.eventType}`); + context.log(`Subject: ${event.subject}`); + if (event.eventType === "Microsoft.Storage.BlobCreated") { + const data = event.data as { url: string }; + context.log(`New blob: ${data.url}`); + } +} +``` + +## Common Pitfalls +- **One system topic per source**: Each Azure resource can have only one system topic in a given region. Attempting to create a second fails with a conflict error. +- **Topic type must match source**: The `topicType` must exactly match the Azure provider (e.g., `Microsoft.Storage.StorageAccounts`, not `Microsoft.Storage`). Invalid types produce unhelpful errors. +- **Location must match source**: The system topic location must match the source resource's location, or deployment fails. +- **Event subscription separate resource**: The system topic alone doesn't route events. You must create an event subscription (child resource) to deliver events to handlers. +- **Storage event filtering**: Use subject filters (prefix/suffix) on subscriptions to limit events to specific containers or blob paths. + +## Production Backlog Items +- Dead-letter destination with managed identity authentication +- Event delivery retry policies and exponential backoff +- Advanced subject filtering for granular event routing +- Event delivery metrics and monitoring +- Multiple event subscriptions for fan-out patterns diff --git a/azext_prototype/knowledge/services/event-grid.md b/azext_prototype/knowledge/services/event-grid.md index 08db934..3eb0fd6 100644 --- a/azext_prototype/knowledge/services/event-grid.md +++ b/azext_prototype/knowledge/services/event-grid.md @@ -1,297 +1,359 @@ -# Azure Event Grid -> Fully managed event routing service for building event-driven architectures with publish-subscribe semantics. - -## When to Use - -- **Event-driven architectures** -- decouple producers and consumers with reliable event delivery -- **Azure resource events** -- react to Azure resource lifecycle events (blob created, resource group changed, etc.) -- **Custom application events** -- publish domain events from your application for downstream processing -- **Serverless triggers** -- trigger Azure Functions, Logic Apps, or webhooks in response to events -- **Fan-out** -- deliver a single event to multiple subscribers simultaneously -- **Event filtering** -- route events to specific handlers based on event type, subject, or data content - -Prefer Event Grid over Service Bus when you need **event notification** (something happened) rather than **command messaging** (do something). Event Grid excels at fire-and-forget broadcasting; Service Bus excels at reliable, ordered, transactional messaging. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Topic type | Custom Topic | For application-generated events | -| Topic type (alternative) | System Topic | For Azure resource events (auto-created) | -| Schema | CloudEvents v1.0 | Recommended for new implementations | -| Public network access | Enabled (POC) | Flag private endpoint as production backlog item | - -## Terraform Patterns - -### Basic Resource - -```hcl -# Custom Topic -resource "azurerm_eventgrid_topic" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - - input_schema = "CloudEventSchemaV1_0" # Recommended schema - - identity { - type = "SystemAssigned" - } - - public_network_access_enabled = true # Set false when using private endpoint - - tags = var.tags -} - -# Event Subscription (e.g., to Azure Function) -resource "azurerm_eventgrid_event_subscription" "function" { - name = "sub-${var.name}-function" - scope = azurerm_eventgrid_topic.this.id - - azure_function_endpoint { - function_id = var.function_id # Resource ID of the Azure Function - } - - # Optional: filter events - advanced_filter { - string_contains { - key = "subject" - values = ["orders/"] - } - } - - retry_policy { - max_delivery_attempts = 30 - event_time_to_live = 1440 # 24 hours in minutes - } -} - -# Event Subscription (to webhook) -resource "azurerm_eventgrid_event_subscription" "webhook" { - name = "sub-${var.name}-webhook" - scope = azurerm_eventgrid_topic.this.id - - webhook_endpoint { - url = var.webhook_url - } -} - -# System Topic (for Azure resource events) -resource "azurerm_eventgrid_system_topic" "storage" { - name = "systopic-${var.name}-storage" - location = var.location - resource_group_name = var.resource_group_name - source_arm_resource_id = var.storage_account_id - topic_type = "Microsoft.Storage.StorageAccounts" - - identity { - type = "SystemAssigned" - } - - tags = var.tags -} -``` - -### RBAC Assignment - -```hcl -# EventGrid Data Sender -- allows publishing events to topic -resource "azurerm_role_assignment" "event_sender" { - scope = azurerm_eventgrid_topic.this.id - role_definition_name = "EventGrid Data Sender" - principal_id = var.managed_identity_principal_id -} -``` - -RBAC role IDs: -- EventGrid Data Sender: `d5a91429-5739-47e2-a06b-3470a27159e7` - -### Private Endpoint - -```hcl -resource "azurerm_private_endpoint" "eventgrid" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_eventgrid_topic.this.id - subresource_names = ["topic"] - is_manual_connection = false - } - - dynamic "private_dns_zone_group" { - for_each = var.private_dns_zone_id != null ? [1] : [] - content { - name = "dns-zone-group" - private_dns_zone_ids = [var.private_dns_zone_id] - } - } - - tags = var.tags -} -``` - -Private DNS zone: `privatelink.eventgrid.azure.net` - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Event Grid topic') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Tags to apply') -param tags object = {} - -resource topic 'Microsoft.EventGrid/topics@2024-06-01-preview' = { - name: name - location: location - tags: tags - identity: { - type: 'SystemAssigned' - } - properties: { - inputSchema: 'CloudEventSchemaV1_0' - publicNetworkAccess: 'Enabled' // Set 'Disabled' when using private endpoint - } -} - -output id string = topic.id -output name string = topic.name -output endpoint string = topic.properties.endpoint -output principalId string = topic.identity.principalId -``` - -### RBAC Assignment - -```bicep -@description('Principal ID of the managed identity for event publishing') -param publisherPrincipalId string - -var eventGridDataSenderRoleId = 'd5a91429-5739-47e2-a06b-3470a27159e7' - -resource senderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(topic.id, publisherPrincipalId, eventGridDataSenderRoleId) - scope: topic - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', eventGridDataSenderRoleId) - principalId: publisherPrincipalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python - -```python -from azure.eventgrid import EventGridPublisherClient -from azure.core.messaging import CloudEvent -from azure.identity import DefaultAzureCredential - -credential = DefaultAzureCredential(managed_identity_client_id="") -client = EventGridPublisherClient( - endpoint="https://mytopic.eastus-1.eventgrid.azure.net/api/events", - credential=credential, -) - -# Publish a CloudEvent -event = CloudEvent( - type="MyApp.Orders.OrderCreated", - source="/myapp/orders", - data={"order_id": "12345", "customer": "contoso"}, -) -client.send(event) - -# Publish multiple events -events = [ - CloudEvent(type="MyApp.Orders.OrderCreated", source="/myapp/orders", data={"order_id": "12345"}), - CloudEvent(type="MyApp.Orders.OrderCreated", source="/myapp/orders", data={"order_id": "12346"}), -] -client.send(events) -``` - -### C# / .NET - -```csharp -using Azure.Identity; -using Azure.Messaging.EventGrid; -using Azure.Messaging; - -var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions -{ - ManagedIdentityClientId = "" -}); - -var client = new EventGridPublisherClient( - new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"), - credential -); - -// Publish a CloudEvent -var cloudEvent = new CloudEvent( - source: "/myapp/orders", - type: "MyApp.Orders.OrderCreated", - jsonSerializableData: new { OrderId = "12345", Customer = "contoso" } -); - -await client.SendEventAsync(cloudEvent); -``` - -### Node.js - -```typescript -import { EventGridPublisherClient } from "@azure/eventgrid"; -import { DefaultAzureCredential } from "@azure/identity"; - -const credential = new DefaultAzureCredential({ - managedIdentityClientId: "", -}); - -const client = new EventGridPublisherClient( - "https://mytopic.eastus-1.eventgrid.azure.net/api/events", - "CloudEvent", - credential -); - -// Publish a CloudEvent -await client.send([ - { - type: "MyApp.Orders.OrderCreated", - source: "/myapp/orders", - data: { orderId: "12345", customer: "contoso" }, - }, -]); -``` - -## Common Pitfalls - -1. **Schema mismatch** -- Events published with a different schema than the topic expects will be rejected. If the topic uses `CloudEventSchemaV1_0`, all publishers must send CloudEvents. -2. **Webhook validation** -- Webhook endpoints must respond to Event Grid's validation handshake (subscription validation event). Without it, the subscription creation fails. -3. **System topic vs custom topic** -- System topics are auto-created for Azure resource events and cannot be manually created. Custom topics are for application-generated events. -4. **Dead-letter not configured** -- Without dead-letter configuration, events that fail delivery are silently dropped after retry exhaustion. Always configure a dead-letter destination (Storage Blob) for production. -5. **Event ordering** -- Event Grid does not guarantee ordering. If ordering matters, include a sequence number in the event data and handle ordering in the subscriber. -6. **Event size limits** -- Individual events must be under 1 MB. Batch requests must be under 1 MB total. For larger payloads, send a reference (blob URL) instead of the full data. -7. **Retry behavior** -- Event Grid retries failed deliveries with exponential backoff. Default retry: 30 attempts over 24 hours. Configure retry policy based on your latency requirements. - -## Production Backlog Items - -- [ ] Configure dead-letter destination (Azure Blob Storage) for undeliverable events -- [ ] Implement retry policies tuned to subscriber SLA requirements -- [ ] Enable advanced filtering to reduce unnecessary event delivery -- [ ] Configure private endpoints and disable public network access -- [ ] Set up monitoring alerts for delivery failures and dead-lettered events -- [ ] Implement event schema validation in subscribers -- [ ] Configure event subscriptions with expiration times for temporary integrations -- [ ] Review and implement event batching for high-throughput scenarios -- [ ] Set up Azure Monitor diagnostic settings for topic-level metrics +--- +service_namespace: Microsoft.EventGrid/topics +display_name: Azure Event Grid +--- + +# Azure Event Grid +> Fully managed event routing service for building event-driven architectures with publish-subscribe semantics. + +## When to Use + +- **Event-driven architectures** -- decouple producers and consumers with reliable event delivery +- **Azure resource events** -- react to Azure resource lifecycle events (blob created, resource group changed, etc.) +- **Custom application events** -- publish domain events from your application for downstream processing +- **Serverless triggers** -- trigger Azure Functions, Logic Apps, or webhooks in response to events +- **Fan-out** -- deliver a single event to multiple subscribers simultaneously +- **Event filtering** -- route events to specific handlers based on event type, subject, or data content + +Prefer Event Grid over Service Bus when you need **event notification** (something happened) rather than **command messaging** (do something). Event Grid excels at fire-and-forget broadcasting; Service Bus excels at reliable, ordered, transactional messaging. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Topic type | Custom Topic | For application-generated events | +| Topic type (alternative) | System Topic | For Azure resource events (auto-created) | +| Schema | CloudEvents v1.0 | Recommended for new implementations | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +# Custom Topic +resource "azapi_resource" "topic" { + type = "Microsoft.EventGrid/topics@2024-06-01-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + inputSchema = "CloudEventSchemaV1_0" # Recommended schema + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + } + } + + tags = var.tags + + response_export_values = ["properties.endpoint"] +} + +# Event Subscription (e.g., to Azure Function) +resource "azapi_resource" "sub_function" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = "sub-${var.name}-function" + parent_id = azapi_resource.topic.id + + body = { + properties = { + destination = { + endpointType = "AzureFunction" + properties = { + resourceId = var.function_id # Resource ID of the Azure Function + } + } + filter = { + advancedFilters = [ + { + operatorType = "StringContains" + key = "subject" + values = ["orders/"] + } + ] + } + retryPolicy = { + maxDeliveryAttempts = 30 + eventTimeToLiveInMinutes = 1440 # 24 hours + } + } + } +} + +# Event Subscription (to webhook) +resource "azapi_resource" "sub_webhook" { + type = "Microsoft.EventGrid/topics/eventSubscriptions@2024-06-01-preview" + name = "sub-${var.name}-webhook" + parent_id = azapi_resource.topic.id + + body = { + properties = { + destination = { + endpointType = "WebHook" + properties = { + endpointUrl = var.webhook_url + } + } + } + } +} + +# System Topic (for Azure resource events) +resource "azapi_resource" "system_topic" { + type = "Microsoft.EventGrid/systemTopics@2024-06-01-preview" + name = "systopic-${var.name}-storage" + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + source = var.storage_account_id + topicType = "Microsoft.Storage.StorageAccounts" + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# EventGrid Data Sender -- allows publishing events to topic +resource "azapi_resource" "event_sender_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.topic.id}${var.managed_identity_principal_id}eg-sender") + parent_id = azapi_resource.topic.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/d5a91429-5739-47e2-a06b-3470a27159e7" # EventGrid Data Sender + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +RBAC role IDs: +- EventGrid Data Sender: `d5a91429-5739-47e2-a06b-3470a27159e7` + +### Private Endpoint + +```hcl +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.topic.id + groupIds = ["topic"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.eventgrid.azure.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Event Grid topic') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource topic 'Microsoft.EventGrid/topics@2024-06-01-preview' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + inputSchema: 'CloudEventSchemaV1_0' + publicNetworkAccess: 'Disabled' // Unless told otherwise, disabled per governance policy + } +} + +output id string = topic.id +output name string = topic.name +output endpoint string = topic.properties.endpoint +output principalId string = topic.identity.principalId +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity for event publishing') +param publisherPrincipalId string + +var eventGridDataSenderRoleId = 'd5a91429-5739-47e2-a06b-3470a27159e7' + +resource senderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(topic.id, publisherPrincipalId, eventGridDataSenderRoleId) + scope: topic + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', eventGridDataSenderRoleId) + principalId: publisherPrincipalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python + +```python +from azure.eventgrid import EventGridPublisherClient +from azure.core.messaging import CloudEvent +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential(managed_identity_client_id="") +client = EventGridPublisherClient( + endpoint="https://mytopic.eastus-1.eventgrid.azure.net/api/events", + credential=credential, +) + +# Publish a CloudEvent +event = CloudEvent( + type="MyApp.Orders.OrderCreated", + source="/myapp/orders", + data={"order_id": "12345", "customer": "contoso"}, +) +client.send(event) + +# Publish multiple events +events = [ + CloudEvent(type="MyApp.Orders.OrderCreated", source="/myapp/orders", data={"order_id": "12345"}), + CloudEvent(type="MyApp.Orders.OrderCreated", source="/myapp/orders", data={"order_id": "12346"}), +] +client.send(events) +``` + +### C# / .NET + +```csharp +using Azure.Identity; +using Azure.Messaging.EventGrid; +using Azure.Messaging; + +var credential = new DefaultAzureCredential(new DefaultAzureCredentialOptions +{ + ManagedIdentityClientId = "" +}); + +var client = new EventGridPublisherClient( + new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"), + credential +); + +// Publish a CloudEvent +var cloudEvent = new CloudEvent( + source: "/myapp/orders", + type: "MyApp.Orders.OrderCreated", + jsonSerializableData: new { OrderId = "12345", Customer = "contoso" } +); + +await client.SendEventAsync(cloudEvent); +``` + +### Node.js + +```typescript +import { EventGridPublisherClient } from "@azure/eventgrid"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential({ + managedIdentityClientId: "", +}); + +const client = new EventGridPublisherClient( + "https://mytopic.eastus-1.eventgrid.azure.net/api/events", + "CloudEvent", + credential +); + +// Publish a CloudEvent +await client.send([ + { + type: "MyApp.Orders.OrderCreated", + source: "/myapp/orders", + data: { orderId: "12345", customer: "contoso" }, + }, +]); +``` + +## Common Pitfalls + +1. **Schema mismatch** -- Events published with a different schema than the topic expects will be rejected. If the topic uses `CloudEventSchemaV1_0`, all publishers must send CloudEvents. +2. **Webhook validation** -- Webhook endpoints must respond to Event Grid's validation handshake (subscription validation event). Without it, the subscription creation fails. +3. **System topic vs custom topic** -- System topics are auto-created for Azure resource events and cannot be manually created. Custom topics are for application-generated events. +4. **Dead-letter not configured** -- Without dead-letter configuration, events that fail delivery are silently dropped after retry exhaustion. Always configure a dead-letter destination (Storage Blob) for production. +5. **Event ordering** -- Event Grid does not guarantee ordering. If ordering matters, include a sequence number in the event data and handle ordering in the subscriber. +6. **Event size limits** -- Individual events must be under 1 MB. Batch requests must be under 1 MB total. For larger payloads, send a reference (blob URL) instead of the full data. +7. **Retry behavior** -- Event Grid retries failed deliveries with exponential backoff. Default retry: 30 attempts over 24 hours. Configure retry policy based on your latency requirements. + +## Production Backlog Items + +- [ ] Configure dead-letter destination (Azure Blob Storage) for undeliverable events +- [ ] Implement retry policies tuned to subscriber SLA requirements +- [ ] Enable advanced filtering to reduce unnecessary event delivery +- [ ] Configure private endpoints and disable public network access +- [ ] Set up monitoring alerts for delivery failures and dead-lettered events +- [ ] Implement event schema validation in subscribers +- [ ] Configure event subscriptions with expiration times for temporary integrations +- [ ] Review and implement event batching for high-throughput scenarios +- [ ] Set up Azure Monitor diagnostic settings for topic-level metrics diff --git a/azext_prototype/knowledge/services/event-hub-consumer-group.md b/azext_prototype/knowledge/services/event-hub-consumer-group.md new file mode 100644 index 0000000..e54b5dd --- /dev/null +++ b/azext_prototype/knowledge/services/event-hub-consumer-group.md @@ -0,0 +1,128 @@ +--- +service_namespace: Microsoft.EventHub/namespaces/eventhubs/consumergroups +display_name: Event Hub Consumer Group +depends_on: + - Microsoft.EventHub/namespaces/eventhubs +--- + +# Event Hub Consumer Group + +> A named view of an event hub's event stream. Each consumer group maintains independent read positions, enabling multiple downstream processors. + +## When to Use +- Each application or processing pipeline needs its own consumer group +- The default `$Default` consumer group should not be shared across applications +- Create separate consumer groups for development, testing, and production readers + +## POC Defaults +- **Name**: Application-specific (e.g., `worker-processor`, `analytics-reader`) +- **Default**: `$Default` exists automatically — create additional groups as needed + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "consumer_group" { + type = "Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01" + name = var.consumer_group_name + parent_id = azapi_resource.event_hub.id + + body = { + properties = { + userMetadata = var.description + } + } +} +``` + +### RBAC Assignment +```hcl +# Consumer group access is inherited from the event hub/namespace RBAC. +# Event Hubs Data Receiver role grants read access across all consumer groups. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param consumerGroupName string + +resource consumerGroup 'Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01' = { + parent: eventHub + name: consumerGroupName + properties: { + userMetadata: 'Worker processing pipeline' + } +} + +output consumerGroupId string = consumerGroup.id +output consumerGroupName string = consumerGroup.name +``` + +## Application Code + +### Python +```python +from azure.eventhub import EventHubConsumerClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +consumer = EventHubConsumerClient( + fully_qualified_namespace=".servicebus.windows.net", + eventhub_name=event_hub_name, + consumer_group=consumer_group_name, + credential=credential +) + +async def on_event(partition_context, event): + print(event.body_as_str()) + await partition_context.update_checkpoint(event) + +async with consumer: + await consumer.receive(on_event=on_event) +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Messaging.EventHubs.Consumer; + +var credential = new DefaultAzureCredential(); +var consumer = new EventHubConsumerClient( + consumerGroupName, ".servicebus.windows.net", + eventHubName, credential); + +await foreach (var partitionEvent in consumer.ReadEventsAsync()) +{ + Console.WriteLine(partitionEvent.Data.EventBody.ToString()); +} +``` + +### Node.js +```typescript +import { EventHubConsumerClient } from "@azure/event-hubs"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const consumer = new EventHubConsumerClient( + consumerGroupName, ".servicebus.windows.net", + eventHubName, credential +); + +const subscription = consumer.subscribe({ + processEvents: async (events) => { + for (const event of events) console.log(event.body); + }, + processError: async (err) => console.error(err), +}); +``` + +## Common Pitfalls +- **$Default is shared**: The default consumer group is shared by all readers that don't specify one. Create dedicated consumer groups. +- **Max 20 consumer groups**: Standard tier supports 20 consumer groups per event hub. Premium supports unlimited. +- **Checkpoint storage**: Consumer groups need external checkpoint storage (Azure Blob Storage) for reliable offset tracking. + +## Production Backlog Items +- Checkpoint storage configuration for reliable offset management +- Consumer group monitoring for lag detection +- Separate consumer groups per environment (dev, staging, prod) diff --git a/azext_prototype/knowledge/services/event-hub.md b/azext_prototype/knowledge/services/event-hub.md new file mode 100644 index 0000000..5ecdb4f --- /dev/null +++ b/azext_prototype/knowledge/services/event-hub.md @@ -0,0 +1,126 @@ +--- +service_namespace: Microsoft.EventHub/namespaces/eventhubs +display_name: Event Hub +depends_on: + - Microsoft.EventHub/namespaces +--- + +# Event Hub + +> A named event stream within an Event Hub namespace. High-throughput, partitioned log for event ingestion and processing. + +## When to Use +- High-volume event ingestion (millions of events per second) +- Streaming data pipelines (IoT telemetry, application logs, click streams) +- When multiple consumer groups need independent read positions on the same stream + +## POC Defaults +- **Partition count**: 2 (minimum, sufficient for POC) +- **Message retention**: 1 day +- **Capture**: Disabled (not needed for POC) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "event_hub" { + type = "Microsoft.EventHub/namespaces/eventhubs@2024-01-01" + name = var.event_hub_name + parent_id = azapi_resource.eventhub_namespace.id + + body = { + properties = { + partitionCount = 2 + messageRetentionInDays = 1 + } + } +} +``` + +### RBAC Assignment +```hcl +# Event hub access is granted at the namespace level: +# Azure Event Hubs Data Sender: 2b629674-e913-4c01-ae53-ef4638d8f975 +# Azure Event Hubs Data Receiver: a638d3c7-ab3a-418d-83e6-5f17a39d4fde +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param eventHubName string + +resource eventHub 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = { + parent: eventHubNamespace + name: eventHubName + properties: { + partitionCount: 2 + messageRetentionInDays: 1 + } +} + +output eventHubId string = eventHub.id +output eventHubName string = eventHub.name +``` + +## Application Code + +### Python +```python +from azure.eventhub import EventHubProducerClient, EventData +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +producer = EventHubProducerClient( + fully_qualified_namespace=".servicebus.windows.net", + eventhub_name=event_hub_name, + credential=credential +) + +batch = await producer.create_batch() +batch.add(EventData("Event data")) +await producer.send_batch(batch) +await producer.close() +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Messaging.EventHubs; +using Azure.Messaging.EventHubs.Producer; + +var credential = new DefaultAzureCredential(); +var producer = new EventHubProducerClient( + ".servicebus.windows.net", eventHubName, credential); + +using var batch = await producer.CreateBatchAsync(); +batch.TryAdd(new EventData("Event data")); +await producer.SendAsync(batch); +``` + +### Node.js +```typescript +import { EventHubProducerClient } from "@azure/event-hubs"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const producer = new EventHubProducerClient( + ".servicebus.windows.net", eventHubName, credential +); + +const batch = await producer.createBatch(); +batch.tryAdd({ body: "Event data" }); +await producer.sendBatch(batch); +await producer.close(); +``` + +## Common Pitfalls +- **Partition count is immutable**: Cannot be changed after creation. Plan for growth. +- **Ordering is per-partition**: Events are ordered within a partition, not across partitions. Use partition keys for related events. +- **Consumer groups**: Each consumer group maintains independent read positions. Create separate consumer groups for each downstream processor. + +## Production Backlog Items +- Event capture to Azure Storage or Data Lake for archival +- Increased partition count for higher throughput +- Schema registry for event schema evolution +- Geo-disaster recovery configuration diff --git a/azext_prototype/knowledge/services/event-hubs.md b/azext_prototype/knowledge/services/event-hubs.md new file mode 100644 index 0000000..03863da --- /dev/null +++ b/azext_prototype/knowledge/services/event-hubs.md @@ -0,0 +1,222 @@ +--- +service_namespace: Microsoft.EventHub/namespaces +display_name: Azure Event Hubs +--- + +# Azure Event Hubs +> Fully managed real-time data ingestion service capable of receiving and processing millions of events per second with low latency and high throughput. + +## When to Use + +- **Event streaming** -- high-throughput ingestion of telemetry, logs, and clickstream data +- **Event-driven architectures** -- decouple producers from consumers with partitioned event streams +- **IoT data ingestion** -- collect device telemetry at massive scale +- **Log aggregation** -- centralize application and infrastructure logs for downstream processing +- **Kafka replacement** -- Event Hubs exposes a Kafka-compatible endpoint (no code changes needed) +- **Stream processing** -- feed into Azure Stream Analytics, Azure Functions, or custom consumers + +Prefer Event Hubs over Service Bus when you need high-throughput streaming with partitioned consumers. Use Service Bus for transactional message queuing with ordering guarantees and dead-lettering on individual messages. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | 1 consumer group, 100 brokered connections, 1 day retention | +| SKU (with Kafka) | Standard | Kafka endpoint, 20 consumer groups, 7 day retention | +| Throughput units | 1 | Auto-inflate disabled for POC cost control | +| Partition count | 2 | Minimum; sufficient for POC throughput | +| Message retention | 1 day (Basic) / 7 days (Standard) | Increase for replay scenarios | +| Authentication | AAD (RBAC) | Disable SAS keys when possible | +| Public network access | Enabled | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "eventhub_namespace" { + type = "Microsoft.EventHub/namespaces@2024-01-01" + name = var.namespace_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Basic" + tier = "Basic" + capacity = 1 # Throughput units + } + properties = { + isAutoInflateEnabled = false + disableLocalAuth = true # CRITICAL: Disable SAS keys, enforce AAD + publicNetworkAccess = "Enabled" # Disable for production + minimumTlsVersion = "1.2" + } + } + + tags = var.tags +} + +resource "azapi_resource" "eventhub" { + type = "Microsoft.EventHub/namespaces/eventhubs@2024-01-01" + name = var.eventhub_name + parent_id = azapi_resource.eventhub_namespace.id + + body = { + properties = { + partitionCount = 2 + messageRetentionInDays = 1 + } + } +} +``` + +### Consumer Group + +```hcl +resource "azapi_resource" "consumer_group" { + type = "Microsoft.EventHub/namespaces/eventhubs/consumergroups@2024-01-01" + name = var.consumer_group_name + parent_id = azapi_resource.eventhub.id + + body = { + properties = { + userMetadata = "Consumer group for ${var.application_name}" + } + } +} +``` + +### RBAC Assignment + +```hcl +# Azure Event Hubs Data Sender -- send events +resource "azapi_resource" "eventhub_sender_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.eventhub_namespace.id}${var.managed_identity_principal_id}eventhub-sender") + parent_id = azapi_resource.eventhub_namespace.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/2b629674-e913-4c01-ae53-ef4638d8f975" # Azure Event Hubs Data Sender + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Azure Event Hubs Data Receiver -- receive events +resource "azapi_resource" "eventhub_receiver_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.eventhub_namespace.id}${var.managed_identity_principal_id}eventhub-receiver") + parent_id = azapi_resource.eventhub_namespace.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/a638d3c7-ab3a-418d-83e6-5f17a39d4fde" # Azure Event Hubs Data Receiver + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Event Hubs namespace') +param namespaceName string + +@description('Name of the event hub') +param eventHubName string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource namespace 'Microsoft.EventHub/namespaces@2024-01-01' = { + name: namespaceName + location: location + tags: tags + sku: { + name: 'Basic' + tier: 'Basic' + capacity: 1 + } + properties: { + isAutoInflateEnabled: false + disableLocalAuth: true + publicNetworkAccess: 'Enabled' + minimumTlsVersion: '1.2' + } +} + +resource eventHub 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = { + parent: namespace + name: eventHubName + properties: { + partitionCount: 2 + messageRetentionInDays: 1 + } +} + +output namespaceId string = namespace.id +output namespaceName string = namespace.name +output eventHubName string = eventHub.name +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity') +param principalId string + +// Azure Event Hubs Data Sender +resource senderRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(namespace.id, principalId, '2b629674-e913-4c01-ae53-ef4638d8f975') + scope: namespace + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '2b629674-e913-4c01-ae53-ef4638d8f975') // Azure Event Hubs Data Sender + principalId: principalId + principalType: 'ServicePrincipal' + } +} + +// Azure Event Hubs Data Receiver +resource receiverRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(namespace.id, principalId, 'a638d3c7-ab3a-418d-83e6-5f17a39d4fde') + scope: namespace + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'a638d3c7-ab3a-418d-83e6-5f17a39d4fde') // Azure Event Hubs Data Receiver + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Using SAS keys instead of AAD | Secrets in config, rotation burden | Set `disableLocalAuth = true`, use RBAC roles | +| Too few partitions | Cannot scale consumers beyond partition count; partitions cannot be increased after creation | Plan partition count based on expected consumer parallelism (2 for POC, 4-32 for production) | +| Forgetting consumer groups | Multiple consumers sharing `$Default` group compete for messages | Create dedicated consumer groups per consuming application | +| Basic tier limitations | No Kafka endpoint, 1 consumer group, 256 KB message size, 1 day retention | Use Standard tier if Kafka compatibility or multiple consumer groups are needed | +| Checkpoint storage missing | Consumers lose track of position, reprocess events | Provision a Storage Account with Blob Data Contributor for checkpoint storage | +| Not handling partitioned ordering | Events only ordered within a partition | Use partition keys to group related events to the same partition | + +## Production Backlog Items + +- [ ] Upgrade to Standard or Premium tier for Kafka support and higher limits +- [ ] Enable private endpoint and disable public network access +- [ ] Configure auto-inflate for throughput scaling (Standard tier) +- [ ] Set up capture to Azure Storage or Data Lake for event archival +- [ ] Configure geo-disaster recovery (namespace pairing) +- [ ] Set up monitoring alerts (throttled requests, incoming/outgoing messages, errors) +- [ ] Review partition count for production throughput requirements +- [ ] Enable diagnostic logging to Log Analytics workspace +- [ ] Configure network rules and IP filtering diff --git a/azext_prototype/knowledge/services/expressroute-peering.md b/azext_prototype/knowledge/services/expressroute-peering.md new file mode 100644 index 0000000..ead3314 --- /dev/null +++ b/azext_prototype/knowledge/services/expressroute-peering.md @@ -0,0 +1,123 @@ +--- +service_namespace: Microsoft.Network/expressRouteCircuits/peerings +display_name: ExpressRoute Peering +depends_on: + - Microsoft.Network/expressRouteCircuits +--- + +# ExpressRoute Peering + +> BGP peering configuration on an ExpressRoute circuit that establishes routing between on-premises networks and Azure (private peering) or Microsoft services (Microsoft peering). + +## When to Use +- **Azure Private Peering** -- access Azure VNet resources (VMs, databases, storage private endpoints) over ExpressRoute +- **Microsoft Peering** -- access Microsoft 365 and Azure PaaS services (Storage, SQL) over ExpressRoute with route filters +- Every ExpressRoute circuit requires at least one peering configuration to route traffic +- Private peering is the most common; Microsoft peering requires route filter approval + +Azure Public Peering is deprecated. Use Microsoft Peering with route filters for PaaS service access. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Peering type | AzurePrivatePeering | Most common; direct VNet access | +| Peer ASN | Customer-provided | Your on-premises BGP ASN | +| Primary subnet | /30 | e.g., 10.0.0.0/30 -- 2 usable IPs | +| Secondary subnet | /30 | e.g., 10.0.0.4/30 -- separate from primary | +| VLAN ID | Provider-assigned | Must match provider's circuit configuration | +| Shared key | Optional | MD5 hash for BGP session authentication | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "private_peering" { + type = "Microsoft.Network/expressRouteCircuits/peerings@2024-01-01" + name = "AzurePrivatePeering" + parent_id = azapi_resource.expressroute_circuit.id + + body = { + properties = { + peeringType = "AzurePrivatePeering" + peerASN = var.peer_asn # e.g., 65515 + primaryPeerAddressPrefix = var.primary_subnet # e.g., "10.0.0.0/30" + secondaryPeerAddressPrefix = var.secondary_subnet # e.g., "10.0.0.4/30" + vlanId = var.vlan_id # e.g., 200 + sharedKey = var.shared_key # Optional MD5 key + } + } +} +``` + +### RBAC Assignment + +```hcl +# Peering management inherits from the parent ExpressRoute circuit RBAC. +# Network Contributor (4d97b98b-1d4f-4787-a291-c67834d212e7) on the circuit or resource group. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('On-premises BGP ASN') +param peerAsn int + +@description('Primary peer address prefix (/30)') +param primarySubnet string + +@description('Secondary peer address prefix (/30)') +param secondarySubnet string + +@description('VLAN ID for the peering') +param vlanId int + +resource privatePeering 'Microsoft.Network/expressRouteCircuits/peerings@2024-01-01' = { + parent: expressRouteCircuit + name: 'AzurePrivatePeering' + properties: { + peeringType: 'AzurePrivatePeering' + peerASN: peerAsn + primaryPeerAddressPrefix: primarySubnet + secondaryPeerAddressPrefix: secondarySubnet + vlanId: vlanId + } +} + +output peeringId string = privatePeering.id +output peeringState string = privatePeering.properties.state +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. ExpressRoute peering establishes network-layer connectivity; applications use the same Azure SDK endpoints regardless of whether traffic flows over ExpressRoute or the internet. + +### C# +Infrastructure -- transparent to application code. ExpressRoute peering establishes network-layer connectivity; applications use the same Azure SDK endpoints regardless of whether traffic flows over ExpressRoute or the internet. + +### Node.js +Infrastructure -- transparent to application code. ExpressRoute peering establishes network-layer connectivity; applications use the same Azure SDK endpoints regardless of whether traffic flows over ExpressRoute or the internet. + +## Common Pitfalls + +1. **Peering name must be exact** -- The name must be `AzurePrivatePeering` or `MicrosoftPeering` exactly. Custom names cause deployment failures. +2. **Overlapping /30 subnets** -- Primary and secondary subnets must not overlap with each other or with any VNet address space. Use RFC 1918 ranges not in your Azure VNets. +3. **VLAN ID mismatch** -- The VLAN ID must match what the connectivity provider has configured. A mismatch results in the peering staying in a `NotProvisioned` state. +4. **Peer ASN conflicts** -- The ASN must not conflict with Azure's reserved ASNs (12076, 65515, 65520). Using a conflicting ASN causes BGP session failures. +5. **Circuit must be provisioned first** -- The ExpressRoute circuit must be in `Provisioned` state (by the connectivity provider) before peering can be configured. Deploying peering on an `Enabled` circuit will succeed but the BGP session won't establish. +6. **BFD not enabled by default** -- Bidirectional Forwarding Detection speeds up failover but must be explicitly enabled. Without it, BGP failover can take 60-90 seconds. +7. **Microsoft Peering requires route filters** -- Without a route filter attached, no routes are advertised over Microsoft Peering. The peering appears active but no traffic flows. + +## Production Backlog Items + +- [ ] Enable BFD (Bidirectional Forwarding Detection) for faster failover +- [ ] Configure MD5 authentication (shared key) for BGP session security +- [ ] Set up route filters for Microsoft Peering to limit advertised routes +- [ ] Implement redundant circuits across different peering locations +- [ ] Configure connection monitoring with Network Watcher +- [ ] Document BGP community values for traffic engineering +- [ ] Plan IPv6 peering if dual-stack is required diff --git a/azext_prototype/knowledge/services/expressroute.md b/azext_prototype/knowledge/services/expressroute.md new file mode 100644 index 0000000..108c089 --- /dev/null +++ b/azext_prototype/knowledge/services/expressroute.md @@ -0,0 +1,331 @@ +--- +service_namespace: Microsoft.Network/expressRouteCircuits +display_name: Azure ExpressRoute +--- + +# Azure ExpressRoute +> Private, dedicated, high-bandwidth connection between on-premises networks and Azure, bypassing the public internet for consistent latency, higher throughput, and enhanced security. + +## When to Use + +- **High-bandwidth hybrid connectivity** -- 50 Mbps to 100 Gbps dedicated circuits +- **Latency-sensitive workloads** -- predictable latency without internet variability +- **Regulatory compliance** -- data never traverses the public internet +- **Large data transfers** -- bulk data migration, backup/replication, big data workloads +- **Microsoft 365 connectivity** -- direct peering to Microsoft services (with Microsoft peering) +- NOT suitable for: cost-constrained POC (use VPN Gateway), internet-only workloads, or single-developer remote access (use P2S VPN) + +Choose ExpressRoute for production hybrid connectivity. Choose VPN Gateway for POC/dev scenarios or as an ExpressRoute backup. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Premium for cross-region, >4000 routes | +| Bandwidth | 50 Mbps | Minimum; sufficient for POC validation | +| Peering type | Azure Private | Direct access to VNet resources | +| Provider | Varies | Must contract with connectivity provider | +| Gateway SKU | ErGw1AZ | Zone-redundant; matches ExpressRoute circuit | +| Subnet name | GatewaySubnet | Shared with VPN Gateway if coexisting | +| Subnet size | /27 minimum | /27 supports coexistence with VPN Gateway | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "expressroute_circuit" { + type = "Microsoft.Network/expressRouteCircuits@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_MeteredData" # or "Premium_MeteredData", "Standard_UnlimitedData" + tier = "Standard" + family = "MeteredData" # or "UnlimitedData" + } + properties = { + serviceProviderProperties = { + serviceProviderName = var.provider_name # e.g., "Equinix" + peeringLocation = var.peering_location # e.g., "Washington DC" + bandwidthInMbps = var.bandwidth # e.g., 50 + } + allowClassicOperations = false + } + } + + tags = var.tags + + response_export_values = ["properties.serviceKey", "properties.serviceProviderProvisioningState"] +} +``` + +### ExpressRoute Gateway + +```hcl +resource "azapi_resource" "gateway_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "GatewaySubnet" + parent_id = var.virtual_network_id + + body = { + properties = { + addressPrefix = var.gateway_subnet_prefix # e.g., "10.0.254.0/27" + } + } +} + +resource "azapi_resource" "er_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-ergw-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "er_gateway" { + type = "Microsoft.Network/virtualNetworkGateways@2024-01-01" + name = "ergw-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + gatewayType = "ExpressRoute" + sku = { + name = "ErGw1AZ" + tier = "ErGw1AZ" + } + ipConfigurations = [ + { + name = "er-ip-config" + properties = { + publicIPAddress = { + id = azapi_resource.er_pip.id + } + subnet = { + id = azapi_resource.gateway_subnet.id + } + privateIPAllocationMethod = "Dynamic" + } + } + ] + } + } + + tags = var.tags +} +``` + +### ExpressRoute Connection + +```hcl +resource "azapi_resource" "er_connection" { + type = "Microsoft.Network/connections@2024-01-01" + name = "conn-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + connectionType = "ExpressRoute" + virtualNetworkGateway1 = { + id = azapi_resource.er_gateway.id + } + peer = { + id = azapi_resource.expressroute_circuit.id + } + authorizationKey = var.authorization_key # null if same subscription + } + } + + tags = var.tags +} +``` + +### Private Peering + +```hcl +resource "azapi_resource" "private_peering" { + type = "Microsoft.Network/expressRouteCircuits/peerings@2024-01-01" + name = "AzurePrivatePeering" + parent_id = azapi_resource.expressroute_circuit.id + + body = { + properties = { + peeringType = "AzurePrivatePeering" + peerASN = var.peer_asn # On-premises BGP ASN + primaryPeerAddressPrefix = var.primary_peer_prefix # e.g., "192.168.1.0/30" + secondaryPeerAddressPrefix = var.secondary_peer_prefix # e.g., "192.168.2.0/30" + vlanId = var.vlan_id # e.g., 100 + } + } +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor for ExpressRoute management +resource "azapi_resource" "er_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.expressroute_circuit.id}-${var.admin_principal_id}-network-contributor") + parent_id = azapi_resource.expressroute_circuit.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +ExpressRoute does not use private endpoints -- it provides the private connectivity layer that enables access to resources with private endpoints from on-premises networks. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the ExpressRoute circuit') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Connectivity provider name') +param providerName string + +@description('Peering location') +param peeringLocation string + +@description('Bandwidth in Mbps') +param bandwidthInMbps int = 50 + +@description('Tags to apply') +param tags object = {} + +resource expressRouteCircuit 'Microsoft.Network/expressRouteCircuits@2024-01-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard_MeteredData' + tier: 'Standard' + family: 'MeteredData' + } + properties: { + serviceProviderProperties: { + serviceProviderName: providerName + peeringLocation: peeringLocation + bandwidthInMbps: bandwidthInMbps + } + allowClassicOperations: false + } +} + +output id string = expressRouteCircuit.id +output serviceKey string = expressRouteCircuit.properties.serviceKey +``` + +### ExpressRoute Gateway + +```bicep +@description('Virtual network ID') +param virtualNetworkId string + +@description('Gateway subnet prefix') +param gatewaySubnetPrefix string = '10.0.254.0/27' + +resource gatewaySubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + name: '${split(virtualNetworkId, '/')[8]}/GatewaySubnet' + properties: { + addressPrefix: gatewaySubnetPrefix + } +} + +resource erPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-ergw-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource erGateway 'Microsoft.Network/virtualNetworkGateways@2024-01-01' = { + name: 'ergw-${name}' + location: location + tags: tags + properties: { + gatewayType: 'ExpressRoute' + sku: { + name: 'ErGw1AZ' + tier: 'ErGw1AZ' + } + ipConfigurations: [ + { + name: 'er-ip-config' + properties: { + publicIPAddress: { + id: erPip.id + } + subnet: { + id: gatewaySubnet.id + } + privateIPAllocationMethod: 'Dynamic' + } + } + ] + } +} + +output gatewayId string = erGateway.id +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Provisioning delay | Circuit requires provider-side provisioning (days to weeks) | Initiate provider provisioning early; circuit is not usable until provider completes | +| Wrong peering location | Cannot connect to provider | Verify provider supports the chosen peering location | +| GatewaySubnet too small | Cannot deploy ER gateway; no room for coexistence | Use /27 minimum to support ER + VPN coexistence | +| Forgetting private peering | No VNet connectivity even with circuit provisioned | Configure Azure Private Peering with correct BGP parameters | +| Service key exposure | Anyone with the key can connect to your circuit | Treat service key as a secret; use authorization keys for cross-subscription | +| Standard SKU route limits | Maximum 4,000 routes per peering | Use Premium SKU if on-premises advertises >4,000 routes | +| Gateway deployment time | ER gateway takes 30-45 minutes to deploy | Plan for long provisioning; do not cancel | +| No redundancy | Single circuit is a single point of failure | Deploy two circuits in different peering locations for production | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Redundant circuits | P1 | Deploy second circuit via different provider/location for HA | +| Premium SKU | P2 | Upgrade for global reach, >4,000 routes, and cross-region VNet linking | +| FastPath | P2 | Enable FastPath on ErGw3AZ for reduced latency to private endpoints | +| ExpressRoute Global Reach | P3 | Enable branch-to-branch connectivity across circuits | +| BFD enablement | P2 | Enable Bidirectional Forwarding Detection for faster failover | +| Connection monitoring | P1 | Enable ExpressRoute connection monitor and diagnostic logging | +| VPN backup | P2 | Configure VPN Gateway as backup path with automatic failover | +| Microsoft peering | P3 | Add Microsoft peering for Microsoft 365 and Azure PaaS public IPs | +| Route filters | P2 | Configure route filters to control which Azure regions/services are advertised | +| Bandwidth upgrade | P3 | Increase circuit bandwidth based on observed utilization | diff --git a/azext_prototype/knowledge/services/fabric.md b/azext_prototype/knowledge/services/fabric.md index 25b2ed5..a7ad7d2 100644 --- a/azext_prototype/knowledge/services/fabric.md +++ b/azext_prototype/knowledge/services/fabric.md @@ -1,246 +1,273 @@ -# Microsoft Fabric -> Unified analytics platform combining data engineering, data science, real-time analytics, data warehousing, and business intelligence in a single SaaS experience with OneLake storage. - -## When to Use - -- **Unified analytics** -- single platform for data engineering (Spark), warehousing (T-SQL), real-time analytics (KQL), and BI (Power BI) -- **Lakehouse architecture** -- Delta Lake format on OneLake with both Spark and T-SQL access -- **Power BI integration** -- native semantic models, DirectLake mode for sub-second queries over large datasets -- **Data mesh / domain-oriented analytics** -- workspaces as domain boundaries with shared OneLake storage -- **Simplified data platform** -- replace separate Synapse, Data Factory, Power BI, and ADLS resources with one platform - -Choose Fabric over individual Azure services (Synapse, ADF, ADLS) when you want a unified experience with simplified management. Choose individual services when you need fine-grained ARM control, VNet integration, or have existing Synapse/ADF investments. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Capacity SKU | F2 | Smallest Fabric capacity; 2 CUs, ~$0.36/hr | -| Capacity auto-pause | Enabled | Pause after inactivity to reduce cost | -| Workspace | Default | One workspace per POC; add more as domains emerge | -| OneLake | Included | Automatic; no separate storage account needed | -| Trial | 60-day free trial | Available per tenant; no capacity purchase needed | - -## Terraform Patterns - -### Basic Resource - -Fabric capacities can be deployed via Terraform. Workspaces, lakehouses, and other items are managed through Fabric REST APIs or the Fabric portal. - -```hcl -resource "azurerm_fabric_capacity" "this" { - name = var.name - resource_group_name = var.resource_group_name - location = var.location - - sku { - name = "F2" # F2, F4, F8, F16, F32, F64, etc. - tier = "Fabric" - } - - administration { - members = var.admin_upns # UPNs of capacity admins - } - - tags = var.tags -} -``` - -### Workspace (via REST API / PowerShell) - -Fabric workspaces cannot be created via Terraform or Bicep. Use the Fabric REST API or PowerShell: - -```bash -# Create workspace via Fabric REST API -curl -X POST "https://api.fabric.microsoft.com/v1/workspaces" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "displayName": "my-poc-workspace", - "capacityId": "", - "description": "POC workspace" - }' -``` - -```powershell -# Or via PowerShell -Install-Module -Name MicrosoftPowerBIMgmt -Connect-PowerBIServiceAccount -New-PowerBIWorkspace -Name "my-poc-workspace" -# Assign to capacity via portal or REST API -``` - -### RBAC Assignment - -Fabric uses its own workspace-level role system rather than ARM RBAC: - -```hcl -# ARM-level: Fabric capacity roles -resource "azurerm_role_assignment" "fabric_contributor" { - scope = azurerm_fabric_capacity.this.id - role_definition_name = "Contributor" - principal_id = var.admin_identity_principal_id -} -``` - -Workspace-level roles (Admin, Member, Contributor, Viewer) are managed through the Fabric portal or REST API, not ARM. - -### Private Endpoint - -Fabric supports private endpoints for the capacity resource: - -```hcl -resource "azurerm_private_endpoint" "fabric" { - count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_fabric_capacity.this.id - subresource_names = ["fabric"] - is_manual_connection = false - } - - tags = var.tags -} -``` - -**Note:** Fabric private endpoints secure connectivity to the capacity from your VNet. OneLake data access goes through the Fabric service — use managed private endpoints in Fabric for data source connections. - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Fabric capacity') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Admin UPNs for the capacity') -param adminMembers array - -@description('Tags to apply') -param tags object = {} - -resource fabricCapacity 'Microsoft.Fabric/capacities@2023-11-01' = { - name: name - location: location - tags: tags - sku: { - name: 'F2' - tier: 'Fabric' - } - properties: { - administration: { - members: adminMembers - } - } -} - -output id string = fabricCapacity.id -output name string = fabricCapacity.name -``` - -### RBAC Assignment - -No data-plane RBAC via ARM -- workspace roles managed through Fabric portal/API. - -## Application Code - -### Python — Spark Notebook (Fabric Runtime) - -```python -# Fabric Spark notebook -- runs in the Fabric Spark runtime -# No pip install needed; libraries pre-installed - -# Read from lakehouse -df = spark.read.format("delta").load("Tables/customers") - -# Transform -from pyspark.sql.functions import col, current_timestamp - -df_enriched = df.withColumn("processed_at", current_timestamp()) \ - .filter(col("status") == "active") - -# Write to lakehouse table -df_enriched.write.format("delta").mode("overwrite").save("Tables/active_customers") -``` - -### Python — Fabric REST API (External) - -```python -from azure.identity import DefaultAzureCredential -import requests - -credential = DefaultAzureCredential() -token = credential.get_token("https://api.fabric.microsoft.com/.default") - -headers = { - "Authorization": f"Bearer {token.token}", - "Content-Type": "application/json", -} - -# List workspaces -response = requests.get("https://api.fabric.microsoft.com/v1/workspaces", headers=headers) -workspaces = response.json()["value"] - -# Run notebook -response = requests.post( - f"https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/items/{notebook_id}/jobs/instances?jobType=RunNotebook", - headers=headers, -) -``` - -### T-SQL — Warehouse / SQL Endpoint - -```sql --- Fabric SQL endpoint (read-only over lakehouse tables) --- or Fabric Warehouse (read-write T-SQL) -SELECT - c.customer_id, - c.name, - SUM(o.total) AS total_spend -FROM lakehouse.dbo.customers c -JOIN lakehouse.dbo.orders o ON c.customer_id = o.customer_id -GROUP BY c.customer_id, c.name -ORDER BY total_spend DESC; -``` - -### KQL — Real-Time Analytics - -```kusto -// Fabric KQL database for real-time streaming data -Events -| where Timestamp > ago(1h) -| summarize Count = count(), AvgDuration = avg(Duration) by bin(Timestamp, 5m), EventType -| order by Timestamp desc -``` - -## Common Pitfalls - -1. **Capacity vs workspace confusion** -- Capacity is the compute resource (ARM-deployed). Workspaces are containers for items (portal/API-managed). Capacity must exist before workspace can be assigned. -2. **Capacity auto-pause delays** -- After pausing, resuming takes 1-2 minutes. First query after resume may time out. Design retry logic. -3. **OneLake shortcuts vs copies** -- Shortcuts provide zero-copy access to external data (ADLS, S3, other lakehouses). Data is not duplicated. Use shortcuts for POC to avoid data movement. -4. **Workspace roles are Fabric-specific** -- Not Azure RBAC. Admin, Member, Contributor, Viewer roles are managed in the Fabric portal, not ARM templates. -5. **Delta Lake format required** -- OneLake tables must be Delta Lake format. Parquet files in the "Files" section are accessible but not queryable via SQL endpoint without conversion. -6. **Capacity Units (CU) throttling** -- F2 has limited CUs. Concurrent Spark jobs and SQL queries share the capacity. Monitor utilization and scale up if throttled. -7. **No VNet injection** -- Unlike Synapse, Fabric doesn't support VNet injection for Spark clusters. Use managed private endpoints and trusted workspace access for data source connectivity. - -## Production Backlog Items - -- [ ] Upgrade capacity from F2 to appropriate size based on workload -- [ ] Configure managed private endpoints for data source connectivity -- [ ] Enable private endpoint access for the capacity -- [ ] Set up Git integration for workspace version control -- [ ] Configure deployment pipelines (Dev → Test → Prod) -- [ ] Implement data governance with Microsoft Purview integration -- [ ] Set up monitoring and alerts for capacity utilization -- [ ] Configure workspace-level access controls and row-level security -- [ ] Enable audit logging for compliance -- [ ] Implement data lineage tracking across items +--- +service_namespace: Microsoft.Fabric/capacities +display_name: Microsoft Fabric +--- + +# Microsoft Fabric +> Unified analytics platform combining data engineering, data science, real-time analytics, data warehousing, and business intelligence in a single SaaS experience with OneLake storage. + +## When to Use + +- **Unified analytics** -- single platform for data engineering (Spark), warehousing (T-SQL), real-time analytics (KQL), and BI (Power BI) +- **Lakehouse architecture** -- Delta Lake format on OneLake with both Spark and T-SQL access +- **Power BI integration** -- native semantic models, DirectLake mode for sub-second queries over large datasets +- **Data mesh / domain-oriented analytics** -- workspaces as domain boundaries with shared OneLake storage +- **Simplified data platform** -- replace separate Synapse, Data Factory, Power BI, and ADLS resources with one platform + +Choose Fabric over individual Azure services (Synapse, ADF, ADLS) when you want a unified experience with simplified management. Choose individual services when you need fine-grained ARM control, VNet integration, or have existing Synapse/ADF investments. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Capacity SKU | F2 | Smallest Fabric capacity; 2 CUs, ~$0.36/hr | +| Capacity auto-pause | Enabled | Pause after inactivity to reduce cost | +| Workspace | Default | One workspace per POC; add more as domains emerge | +| OneLake | Included | Automatic; no separate storage account needed | +| Trial | 60-day free trial | Available per tenant; no capacity purchase needed | + +## Terraform Patterns + +### Basic Resource + +Fabric capacities can be deployed via Terraform. Workspaces, lakehouses, and other items are managed through Fabric REST APIs or the Fabric portal. + +```hcl +resource "azapi_resource" "this" { + type = "Microsoft.Fabric/capacities@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "F2" # F2, F4, F8, F16, F32, F64, etc. + tier = "Fabric" + } + properties = { + administration = { + members = var.admin_upns # UPNs of capacity admins + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### Workspace (via REST API / PowerShell) + +Fabric workspaces cannot be created via Terraform or Bicep. Use the Fabric REST API or PowerShell: + +```bash +# Create workspace via Fabric REST API +curl -X POST "https://api.fabric.microsoft.com/v1/workspaces" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "displayName": "my-poc-workspace", + "capacityId": "", + "description": "POC workspace" + }' +``` + +```powershell +# Or via PowerShell +Install-Module -Name MicrosoftPowerBIMgmt +Connect-PowerBIServiceAccount +New-PowerBIWorkspace -Name "my-poc-workspace" +# Assign to capacity via portal or REST API +``` + +### RBAC Assignment + +Fabric uses its own workspace-level role system rather than ARM RBAC: + +```hcl +# ARM-level: Fabric capacity roles +resource "azapi_resource" "fabric_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.this.id}-contributor") + parent_id = azapi_resource.this.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" + principalId = var.admin_identity_principal_id + } + } +} +``` + +Workspace-level roles (Admin, Member, Contributor, Viewer) are managed through the Fabric portal or REST API, not ARM. + +### Private Endpoint + +Fabric supports private endpoints for the capacity resource: + +```hcl +resource "azapi_resource" "fabric_pe" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.this.id + groupIds = ["fabric"] + } + } + ] + } + } + + tags = var.tags +} +``` + +**Note:** Fabric private endpoints secure connectivity to the capacity from your VNet. OneLake data access goes through the Fabric service — use managed private endpoints in Fabric for data source connections. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Fabric capacity') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Admin UPNs for the capacity') +param adminMembers array + +@description('Tags to apply') +param tags object = {} + +resource fabricCapacity 'Microsoft.Fabric/capacities@2023-11-01' = { + name: name + location: location + tags: tags + sku: { + name: 'F2' + tier: 'Fabric' + } + properties: { + administration: { + members: adminMembers + } + } +} + +output id string = fabricCapacity.id +output name string = fabricCapacity.name +``` + +### RBAC Assignment + +No data-plane RBAC via ARM -- workspace roles managed through Fabric portal/API. + +## Application Code + +### Python — Spark Notebook (Fabric Runtime) + +```python +# Fabric Spark notebook -- runs in the Fabric Spark runtime +# No pip install needed; libraries pre-installed + +# Read from lakehouse +df = spark.read.format("delta").load("Tables/customers") + +# Transform +from pyspark.sql.functions import col, current_timestamp + +df_enriched = df.withColumn("processed_at", current_timestamp()) \ + .filter(col("status") == "active") + +# Write to lakehouse table +df_enriched.write.format("delta").mode("overwrite").save("Tables/active_customers") +``` + +### Python — Fabric REST API (External) + +```python +from azure.identity import DefaultAzureCredential +import requests + +credential = DefaultAzureCredential() +token = credential.get_token("https://api.fabric.microsoft.com/.default") + +headers = { + "Authorization": f"Bearer {token.token}", + "Content-Type": "application/json", +} + +# List workspaces +response = requests.get("https://api.fabric.microsoft.com/v1/workspaces", headers=headers) +workspaces = response.json()["value"] + +# Run notebook +response = requests.post( + f"https://api.fabric.microsoft.com/v1/workspaces/{workspace_id}/items/{notebook_id}/jobs/instances?jobType=RunNotebook", + headers=headers, +) +``` + +### T-SQL — Warehouse / SQL Endpoint + +```sql +-- Fabric SQL endpoint (read-only over lakehouse tables) +-- or Fabric Warehouse (read-write T-SQL) +SELECT + c.customer_id, + c.name, + SUM(o.total) AS total_spend +FROM lakehouse.dbo.customers c +JOIN lakehouse.dbo.orders o ON c.customer_id = o.customer_id +GROUP BY c.customer_id, c.name +ORDER BY total_spend DESC; +``` + +### KQL — Real-Time Analytics + +```kusto +// Fabric KQL database for real-time streaming data +Events +| where Timestamp > ago(1h) +| summarize Count = count(), AvgDuration = avg(Duration) by bin(Timestamp, 5m), EventType +| order by Timestamp desc +``` + +## Common Pitfalls + +1. **Capacity vs workspace confusion** -- Capacity is the compute resource (ARM-deployed). Workspaces are containers for items (portal/API-managed). Capacity must exist before workspace can be assigned. +2. **Capacity auto-pause delays** -- After pausing, resuming takes 1-2 minutes. First query after resume may time out. Design retry logic. +3. **OneLake shortcuts vs copies** -- Shortcuts provide zero-copy access to external data (ADLS, S3, other lakehouses). Data is not duplicated. Use shortcuts for POC to avoid data movement. +4. **Workspace roles are Fabric-specific** -- Not Azure RBAC. Admin, Member, Contributor, Viewer roles are managed in the Fabric portal, not ARM templates. +5. **Delta Lake format required** -- OneLake tables must be Delta Lake format. Parquet files in the "Files" section are accessible but not queryable via SQL endpoint without conversion. +6. **Capacity Units (CU) throttling** -- F2 has limited CUs. Concurrent Spark jobs and SQL queries share the capacity. Monitor utilization and scale up if throttled. +7. **No VNet injection** -- Unlike Synapse, Fabric doesn't support VNet injection for Spark clusters. Use managed private endpoints and trusted workspace access for data source connectivity. + +## Production Backlog Items + +- [ ] Upgrade capacity from F2 to appropriate size based on workload +- [ ] Configure managed private endpoints for data source connectivity +- [ ] Enable private endpoint access for the capacity +- [ ] Set up Git integration for workspace version control +- [ ] Configure deployment pipelines (Dev → Test → Prod) +- [ ] Implement data governance with Microsoft Purview integration +- [ ] Set up monitoring and alerts for capacity utilization +- [ ] Configure workspace-level access controls and row-level security +- [ ] Enable audit logging for compliance +- [ ] Implement data lineage tracking across items diff --git a/azext_prototype/knowledge/services/firewall-policy-rule-collection-group.md b/azext_prototype/knowledge/services/firewall-policy-rule-collection-group.md new file mode 100644 index 0000000..60e6330 --- /dev/null +++ b/azext_prototype/knowledge/services/firewall-policy-rule-collection-group.md @@ -0,0 +1,120 @@ +--- +service_namespace: Microsoft.Network/firewallPolicies/ruleCollectionGroups +display_name: Firewall Rule Collection Group +depends_on: + - Microsoft.Network/firewallPolicies +--- + +# Firewall Rule Collection Group + +> A group of rule collections within a firewall policy. Organizes DNAT, network, and application rules by priority. + +## When to Use +- Organize firewall rules by function (e.g., "AllowInfrastructure", "AllowApplications", "DenyAll") +- Each group has a priority that determines processing order relative to other groups +- Groups contain one or more rule collections + +## POC Defaults +- **Priority**: 100 (allow rules), 200 (application rules), 65000 (deny all) +- **Action**: Allow for application traffic; Deny for catch-all + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "rule_collection_group" { + type = "Microsoft.Network/firewallPolicies/ruleCollectionGroups@2024-01-01" + name = var.group_name + parent_id = azapi_resource.firewall_policy.id + + body = { + properties = { + priority = 100 + ruleCollections = [ + { + ruleCollectionType = "FirewallPolicyFilterRuleCollection" + name = "AllowOutbound" + priority = 100 + action = { type = "Allow" } + rules = [ + { + ruleType = "NetworkRule" + name = "AllowDNS" + ipProtocols = ["UDP"] + sourceAddresses = ["10.0.0.0/16"] + destinationAddresses = ["*"] + destinationPorts = ["53"] + } + ] + } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Rule collection management inherits from the parent firewall policy RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param groupName string + +resource ruleCollectionGroup 'Microsoft.Network/firewallPolicies/ruleCollectionGroups@2024-01-01' = { + parent: firewallPolicy + name: groupName + properties: { + priority: 100 + ruleCollections: [ + { + ruleCollectionType: 'FirewallPolicyFilterRuleCollection' + name: 'AllowOutbound' + priority: 100 + action: { type: 'Allow' } + rules: [ + { + ruleType: 'NetworkRule' + name: 'AllowDNS' + ipProtocols: ['UDP'] + sourceAddresses: ['10.0.0.0/16'] + destinationAddresses: ['*'] + destinationPorts: ['53'] + } + ] + } + ] + } +} +``` + +## Application Code + +### Python +```python +# Firewall rules are infrastructure — transparent to application code. +``` + +### C# +```csharp +// Firewall rules are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Firewall rules are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Priority uniqueness**: Each rule collection group must have a unique priority within the policy. +- **Collection type matters**: Use `FirewallPolicyFilterRuleCollection` for Allow/Deny, `FirewallPolicyNatRuleCollection` for DNAT. +- **Sequential creation**: Rule collection groups within the same policy must be created sequentially (not in parallel). + +## Production Backlog Items +- Application rule collections for FQDN-based filtering +- DNAT rules for inbound port forwarding +- IP Groups for reusable address sets across rules +- Threat intelligence-based filtering rules diff --git a/azext_prototype/knowledge/services/firewall-policy.md b/azext_prototype/knowledge/services/firewall-policy.md new file mode 100644 index 0000000..261c93b --- /dev/null +++ b/azext_prototype/knowledge/services/firewall-policy.md @@ -0,0 +1,98 @@ +--- +service_namespace: Microsoft.Network/firewallPolicies +display_name: Azure Firewall Policy +depends_on: [] +--- + +# Azure Firewall Policy + +> Defines the rule collection groups, threat intelligence settings, and DNS proxy configuration for an Azure Firewall instance. + +## When to Use +- Central rule management for one or more Azure Firewalls +- Define DNAT, network, and application rules in organized collections +- Share policies across firewalls in hub-and-spoke topologies + +## POC Defaults +- **SKU**: Standard (Premium adds TLS inspection, IDPS) +- **Threat intelligence mode**: Alert (log but don't block for POC) +- **DNS proxy**: Enabled + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "firewall_policy" { + type = "Microsoft.Network/firewallPolicies@2024-01-01" + name = var.policy_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { tier = "Standard" } + threatIntelMode = "Alert" + dnsSettings = { + enableProxy = true + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment +```hcl +# Network Contributor role for firewall policy management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param policyName string +param location string = resourceGroup().location +param tags object = {} + +resource firewallPolicy 'Microsoft.Network/firewallPolicies@2024-01-01' = { + name: policyName + location: location + properties: { + sku: { tier: 'Standard' } + threatIntelMode: 'Alert' + dnsSettings: { enableProxy: true } + } + tags: tags +} + +output policyId string = firewallPolicy.id +``` + +## Application Code + +### Python +```python +# Firewall policies are infrastructure — transparent to application code. +``` + +### C# +```csharp +// Firewall policies are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Firewall policies are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Policy vs inline rules**: Always use a policy (not inline rules on the firewall). Policies are reusable and support rule collection groups. +- **SKU must match firewall**: A Standard policy can only be associated with a Standard firewall. +- **Rule processing order**: DNAT rules → Network rules → Application rules. Within each type, lower priority numbers are processed first. + +## Production Backlog Items +- Premium SKU for TLS inspection and IDPS +- Threat intelligence in Deny mode +- IP Groups for reusable address sets +- Policy inheritance for hub-and-spoke topology diff --git a/azext_prototype/knowledge/services/firewall.md b/azext_prototype/knowledge/services/firewall.md new file mode 100644 index 0000000..1f30fde --- /dev/null +++ b/azext_prototype/knowledge/services/firewall.md @@ -0,0 +1,367 @@ +--- +service_namespace: Microsoft.Network/azureFirewalls +display_name: Azure Firewall +--- + +# Azure Firewall +> Cloud-native, fully managed network security service providing centralized network and application rule enforcement, threat intelligence-based filtering, and FQDN-based egress control. + +## When to Use + +- **Centralized egress filtering** -- control and log all outbound traffic from VNets to the internet +- **Hub-spoke network topology** -- central firewall in the hub VNet inspecting traffic between spokes +- **FQDN-based rules** -- allow outbound access to specific domain names (e.g., `*.docker.io`, `pypi.org`) +- **Threat intelligence** -- block traffic to/from known malicious IPs and domains +- **Forced tunneling** -- route all internet-bound traffic through the firewall for inspection +- NOT suitable for: L7 HTTP load balancing (use Application Gateway), global CDN/WAF (use Front Door), or simple NSG-level filtering + +Choose Azure Firewall for centralized network-level security. Pair with Application Gateway or Front Door for L7 web application protection. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Premium for IDPS/TLS inspection; Basic for dev/test | +| Subnet name | AzureFirewallSubnet | Must be exactly this name (Azure requirement) | +| Subnet size | /26 minimum | Required minimum for Azure Firewall | +| Threat intelligence | Alert only | Alert and deny for production | +| DNS proxy | Enabled | Required for FQDN filtering in network rules | +| Public IP | Standard SKU, Static | Required; multiple for SNAT ports | +| Firewall policy | Centralized | Rule collection groups in a firewall policy | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "firewall_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + name = "AzureFirewallSubnet" # Must be exactly this name + parent_id = var.virtual_network_id + + body = { + properties = { + addressPrefix = var.firewall_subnet_prefix # e.g., "10.0.255.0/26" + } + } +} + +resource "azapi_resource" "firewall_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "firewall_policy" { + type = "Microsoft.Network/firewallPolicies@2024-01-01" + name = "policy-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + tier = "Standard" # or "Premium" + } + threatIntelMode = "Alert" # "Deny" for production + dnsSettings = { + enableProxy = true + } + } + } + + tags = var.tags +} + +resource "azapi_resource" "firewall" { + type = "Microsoft.Network/azureFirewalls@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + name = "AZFW_VNet" + tier = "Standard" + } + ipConfigurations = [ + { + name = "fw-ip-config" + properties = { + publicIPAddress = { + id = azapi_resource.firewall_pip.id + } + subnet = { + id = azapi_resource.firewall_subnet.id + } + } + } + ] + firewallPolicy = { + id = azapi_resource.firewall_policy.id + } + } + } + + tags = var.tags + + response_export_values = ["properties.ipConfigurations[0].properties.privateIPAddress"] +} +``` + +### Firewall Policy Rule Collection Group + +```hcl +resource "azapi_resource" "rule_collection_group" { + type = "Microsoft.Network/firewallPolicies/ruleCollectionGroups@2024-01-01" + name = "default-rule-collection-group" + parent_id = azapi_resource.firewall_policy.id + + body = { + properties = { + priority = 200 + ruleCollections = [ + { + ruleCollectionType = "FirewallPolicyFilterRuleCollection" + name = "allow-application-rules" + priority = 100 + action = { + type = "Allow" + } + rules = [ + { + ruleType = "ApplicationRule" + name = "allow-azure-services" + sourceAddresses = ["10.0.0.0/16"] + protocols = [ + { + protocolType = "Https" + port = 443 + } + ] + targetFqdns = [ + "*.azure.com" + "*.microsoft.com" + "*.windows.net" + ] + } + ] + } + { + ruleCollectionType = "FirewallPolicyFilterRuleCollection" + name = "allow-network-rules" + priority = 200 + action = { + type = "Allow" + } + rules = [ + { + ruleType = "NetworkRule" + name = "allow-dns" + sourceAddresses = ["10.0.0.0/16"] + destinationAddresses = ["*"] + destinationPorts = ["53"] + ipProtocols = ["TCP", "UDP"] + } + ] + } + ] + } + } +} +``` + +### Route Table for Forced Tunneling + +```hcl +resource "azapi_resource" "route_table" { + type = "Microsoft.Network/routeTables@2024-01-01" + name = "rt-firewall" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + disableBgpRoutePropagation = true + routes = [ + { + name = "route-to-firewall" + properties = { + addressPrefix = "0.0.0.0/0" + nextHopType = "VirtualAppliance" + nextHopIpAddress = azapi_resource.firewall.output.properties.ipConfigurations[0].properties.privateIPAddress + } + } + ] + } + } + + tags = var.tags +} + +# Associate route table with workload subnets +resource "azapi_update_resource" "subnet_route_table" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + resource_id = var.workload_subnet_id + + body = { + properties = { + addressPrefix = var.workload_subnet_prefix + routeTable = { + id = azapi_resource.route_table.id + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor for firewall management +resource "azapi_resource" "firewall_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.firewall.id}-${var.admin_principal_id}-network-contributor") + parent_id = azapi_resource.firewall.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Azure Firewall does not use private endpoints -- it is deployed into a dedicated subnet (`AzureFirewallSubnet`) and operates as a network virtual appliance within the VNet. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Azure Firewall') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Virtual network ID') +param virtualNetworkId string + +@description('Firewall subnet prefix (min /26)') +param firewallSubnetPrefix string = '10.0.255.0/26' + +@description('Tags to apply') +param tags object = {} + +resource firewallSubnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + name: '${split(virtualNetworkId, '/')[8]}/AzureFirewallSubnet' + properties: { + addressPrefix: firewallSubnetPrefix + } +} + +resource firewallPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource firewallPolicy 'Microsoft.Network/firewallPolicies@2024-01-01' = { + name: 'policy-${name}' + location: location + properties: { + sku: { + tier: 'Standard' + } + threatIntelMode: 'Alert' + dnsSettings: { + enableProxy: true + } + } + tags: tags +} + +resource firewall 'Microsoft.Network/azureFirewalls@2024-01-01' = { + name: name + location: location + tags: tags + properties: { + sku: { + name: 'AZFW_VNet' + tier: 'Standard' + } + ipConfigurations: [ + { + name: 'fw-ip-config' + properties: { + publicIPAddress: { + id: firewallPip.id + } + subnet: { + id: firewallSubnet.id + } + } + } + ] + firewallPolicy: { + id: firewallPolicy.id + } + } +} + +output id string = firewall.id +output privateIpAddress string = firewall.properties.ipConfigurations[0].properties.privateIPAddress +output policyId string = firewallPolicy.id +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Wrong subnet name | Deployment fails | Subnet must be named exactly `AzureFirewallSubnet` | +| Subnet too small | Cannot deploy firewall | Minimum /26 (64 addresses); Azure reserves some | +| Missing route table on workload subnets | Traffic bypasses the firewall | Attach UDR with `0.0.0.0/0 -> VirtualAppliance -> FW private IP` to all workload subnets | +| DNS proxy not enabled | FQDN-based network rules do not resolve | Enable `dnsSettings.enableProxy = true` in firewall policy | +| Threat intel mode set to Deny in POC | Legitimate traffic blocked unexpectedly | Use `Alert` mode during POC; switch to `Deny` for production | +| SNAT port exhaustion | Outbound connections fail under load | Add multiple public IPs to the firewall for more SNAT ports | +| Forgetting to allow Azure management traffic | VM extensions, AKS, updates break | Add application rules for `*.azure.com`, `*.windows.net`, etc. | +| Cost surprise | Standard is ~$1.25/hour even when idle | Consider Basic SKU ($0.395/hour) for POC environments | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Premium SKU upgrade | P2 | Upgrade for IDPS, TLS inspection, and URL filtering | +| Threat intelligence deny mode | P1 | Switch from Alert to Deny for known malicious traffic | +| Diagnostic logging | P1 | Enable firewall logs and metrics to Log Analytics for auditing | +| Availability zones | P1 | Deploy across zones for 99.99% SLA | +| Multiple public IPs | P2 | Add additional public IPs for SNAT port capacity | +| Forced tunneling for all subnets | P1 | Ensure all workload subnets route through firewall | +| Application rule refinement | P2 | Narrow FQDN rules to specific required destinations | +| TLS inspection | P2 | Enable TLS inspection for encrypted traffic analysis (Premium) | +| IP Groups | P3 | Use IP Groups for reusable source/destination address sets | +| Centralized policy management | P3 | Use Azure Firewall Manager for multi-firewall policy management | diff --git a/azext_prototype/knowledge/services/front-door-waf-policy.md b/azext_prototype/knowledge/services/front-door-waf-policy.md new file mode 100644 index 0000000..87b48ae --- /dev/null +++ b/azext_prototype/knowledge/services/front-door-waf-policy.md @@ -0,0 +1,182 @@ +--- +service_namespace: Microsoft.Network/FrontDoorWebApplicationFirewallPolicies +display_name: Front Door WAF Policy +--- + +# Front Door WAF Policy + +> Web Application Firewall policy for Azure Front Door that protects web applications from common exploits (OWASP Top 10), bots, and custom-defined attack patterns with managed and custom rules. + +## When to Use +- **OWASP protection** -- block SQL injection, XSS, command injection, and other OWASP Top 10 attacks +- **Bot protection** -- identify and block malicious bots while allowing legitimate crawlers +- **Geo-filtering** -- block or allow traffic from specific countries/regions +- **Rate limiting** -- prevent DDoS and brute-force attacks at the edge +- **Custom rules** -- match on headers, query strings, IP addresses, or request body for organization-specific protection + +WAF policies are associated with Front Door endpoints or security policies. A single policy can protect multiple endpoints. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Premium_AzureFrontDoor | Classic is deprecated; Standard does not support WAF | +| Mode | Detection | Log but don't block for POC tuning | +| Managed rule set | Microsoft_DefaultRuleSet 2.1 | Latest DRS version | +| Bot rule set | Microsoft_BotManagerRuleSet 1.1 | Optional for POC | +| Custom rules | None | Add as needed | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "waf_policy" { + type = "Microsoft.Network/FrontDoorWebApplicationFirewallPolicies@2024-02-01" + name = var.name + location = "global" # WAF policies are global + parent_id = var.resource_group_id + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + properties = { + policySettings = { + mode = "Detection" # "Prevention" for production + enabledState = "Enabled" + requestBodyCheck = "Enabled" + maxRequestBodySizeInKb = 128 + customBlockResponseBody = null + customBlockResponseStatusCode = 403 + } + managedRules = { + managedRuleSets = [ + { + ruleSetType = "Microsoft_DefaultRuleSet" + ruleSetVersion = "2.1" + ruleSetAction = "Block" + }, + { + ruleSetType = "Microsoft_BotManagerRuleSet" + ruleSetVersion = "1.1" + ruleSetAction = "Block" + } + ] + } + customRules = { + rules = [] + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### RBAC Assignment + +```hcl +# CDN Endpoint Contributor for managing WAF policies +resource "azapi_resource" "cdn_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.waf_policy.id}-${var.principal_id}-cdn-contributor") + parent_id = azapi_resource.waf_policy.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/426e0c7f-0c7e-4658-b36f-ff54d6c29b45" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('WAF policy name') +param name string + +@description('WAF mode') +@allowed(['Detection', 'Prevention']) +param mode string = 'Detection' + +param tags object = {} + +resource wafPolicy 'Microsoft.Network/FrontDoorWebApplicationFirewallPolicies@2024-02-01' = { + name: name + location: 'global' + tags: tags + sku: { + name: 'Premium_AzureFrontDoor' + } + properties: { + policySettings: { + mode: mode + enabledState: 'Enabled' + requestBodyCheck: 'Enabled' + maxRequestBodySizeInKb: 128 + customBlockResponseStatusCode: 403 + } + managedRules: { + managedRuleSets: [ + { + ruleSetType: 'Microsoft_DefaultRuleSet' + ruleSetVersion: '2.1' + ruleSetAction: 'Block' + } + { + ruleSetType: 'Microsoft_BotManagerRuleSet' + ruleSetVersion: '1.1' + ruleSetAction: 'Block' + } + ] + } + customRules: { + rules: [] + } + } +} + +output id string = wafPolicy.id +output name string = wafPolicy.name +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. WAF policies inspect and filter HTTP traffic at the Front Door edge; backend applications receive only allowed requests. + +### C# +Infrastructure -- transparent to application code. WAF policies inspect and filter HTTP traffic at the Front Door edge; backend applications receive only allowed requests. + +### Node.js +Infrastructure -- transparent to application code. WAF policies inspect and filter HTTP traffic at the Front Door edge; backend applications receive only allowed requests. + +## Common Pitfalls + +1. **Location must be `"global"`** -- WAF policies for Front Door are global resources. Specifying a region causes deployment failure. +2. **SKU must match Front Door profile** -- A `Premium_AzureFrontDoor` WAF policy only works with Premium Front Door profiles. Standard Front Door does not support WAF. +3. **Detection mode first** -- Always start in Detection mode to analyze logs before switching to Prevention. Enabling Prevention immediately blocks legitimate traffic that triggers false positives. +4. **Managed rule exclusions** -- When legitimate requests trigger managed rules (e.g., SQL-like query strings), add exclusions for specific rules rather than disabling the entire rule group. +5. **Custom rule priority matters** -- Custom rules execute in priority order (lowest number first). A high-priority Allow rule can bypass subsequent Block rules. +6. **Request body size limit** -- The default 128 KB limit blocks large file uploads. Increase `maxRequestBodySizeInKb` (up to 2 MB) for upload-heavy applications. +7. **WAF logs require diagnostic settings** -- WAF blocks/detections are logged to `FrontDoorWebApplicationFirewallLog`. Enable diagnostic settings to a Log Analytics workspace to see them. +8. **Classic vs Standard/Premium** -- Classic Front Door WAF (`Microsoft.Network/frontDoorWebApplicationFirewallPolicies` with `Classic` SKU) is deprecated. Always use the `Premium_AzureFrontDoor` SKU. + +## Production Backlog Items + +- [ ] Switch from Detection to Prevention mode after tuning +- [ ] Configure managed rule exclusions for known false positives +- [ ] Add custom rate-limiting rules for login and API endpoints +- [ ] Implement geo-filtering custom rules if geographic restriction is needed +- [ ] Enable diagnostic logging to Log Analytics for WAF event analysis +- [ ] Create workbook/dashboard for WAF metrics and blocked requests +- [ ] Add IP allowlist/blocklist custom rules for known good/bad IPs +- [ ] Configure custom block response page with branded error message diff --git a/azext_prototype/knowledge/services/front-door.md b/azext_prototype/knowledge/services/front-door.md index 763f0a5..94702db 100644 --- a/azext_prototype/knowledge/services/front-door.md +++ b/azext_prototype/knowledge/services/front-door.md @@ -1,343 +1,416 @@ -# Azure Front Door -> Global load balancer and CDN with built-in WAF, SSL offloading, and intelligent traffic routing for web applications. - -## When to Use - -- **Global traffic distribution** -- route users to the nearest backend across regions -- **Web Application Firewall (WAF)** -- DDoS protection, bot mitigation, OWASP rule sets -- **Custom domains with managed SSL** -- automated certificate provisioning and renewal -- **CDN for static assets** -- cache static content at edge locations worldwide -- **Multi-backend failover** -- health probes with automatic failover between origins - -Choose Front Door over Azure Application Gateway when you need global (multi-region) distribution or CDN capabilities. Choose Application Gateway for single-region, VNet-internal load balancing with more granular L7 routing. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| Tier | Standard | CDN + basic routing; Premium adds WAF + Private Link | -| WAF | Disabled (POC) | Enable with managed rule sets for production | -| Caching | Enabled for static | Cache CSS/JS/images; bypass for API routes | -| Origin response timeout | 60 seconds | Default; increase for long-running APIs | -| Health probe | Enabled | HEAD requests every 30 seconds | -| Session affinity | Disabled | Stateless backends preferred for POC | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_cdn_frontdoor_profile" "this" { - name = var.name - resource_group_name = var.resource_group_name - sku_name = "Standard_AzureFrontDoor" # or "Premium_AzureFrontDoor" - - tags = var.tags -} - -resource "azurerm_cdn_frontdoor_endpoint" "this" { - name = var.endpoint_name - cdn_frontdoor_profile_id = azurerm_cdn_frontdoor_profile.this.id -} - -resource "azurerm_cdn_frontdoor_origin_group" "this" { - name = "default-origin-group" - cdn_frontdoor_profile_id = azurerm_cdn_frontdoor_profile.this.id - - load_balancing { - sample_size = 4 - successful_samples_required = 3 - } - - health_probe { - path = "/health" - protocol = "Https" - request_type = "HEAD" - interval_in_seconds = 30 - } -} - -resource "azurerm_cdn_frontdoor_origin" "this" { - name = "primary-origin" - cdn_frontdoor_origin_group_id = azurerm_cdn_frontdoor_origin_group.this.id - enabled = true - - host_name = var.origin_hostname # e.g., "myapp.azurewebsites.net" - http_port = 80 - https_port = 443 - origin_host_header = var.origin_hostname - certificate_name_check_enabled = true - priority = 1 - weight = 1000 -} - -resource "azurerm_cdn_frontdoor_route" "this" { - name = "default-route" - cdn_frontdoor_endpoint_id = azurerm_cdn_frontdoor_endpoint.this.id - cdn_frontdoor_origin_group_id = azurerm_cdn_frontdoor_origin_group.this.id - cdn_frontdoor_origin_ids = [azurerm_cdn_frontdoor_origin.this.id] - - supported_protocols = ["Http", "Https"] - patterns_to_match = ["/*"] - forwarding_protocol = "HttpsOnly" - https_redirect_enabled = true - - cache { - query_string_caching_behavior = "IgnoreQueryString" - compression_enabled = true - content_types_to_compress = [ - "text/html", "text/css", "application/javascript", - "application/json", "image/svg+xml" - ] - } -} -``` - -### WAF Policy (Premium tier) - -```hcl -resource "azurerm_cdn_frontdoor_firewall_policy" "this" { - name = replace(var.name, "-", "") # No hyphens allowed - resource_group_name = var.resource_group_name - sku_name = "Premium_AzureFrontDoor" - mode = "Prevention" - - managed_rule { - type = "Microsoft_DefaultRuleSet" - version = "2.1" - action = "Block" - } - - managed_rule { - type = "Microsoft_BotManagerRuleSet" - version = "1.1" - action = "Block" - } - - tags = var.tags -} - -resource "azurerm_cdn_frontdoor_security_policy" "this" { - name = "waf-policy" - cdn_frontdoor_profile_id = azurerm_cdn_frontdoor_profile.this.id - - security_policies { - firewall { - cdn_frontdoor_firewall_policy_id = azurerm_cdn_frontdoor_firewall_policy.this.id - - association { - domain { - cdn_frontdoor_domain_id = azurerm_cdn_frontdoor_endpoint.this.id - } - patterns_to_match = ["/*"] - } - } - } -} -``` - -### RBAC Assignment - -Front Door is typically managed by infrastructure teams. No data-plane RBAC needed -- traffic flows through without authentication at the Front Door level. - -```hcl -# CDN Profile Contributor -- manage Front Door configuration -resource "azurerm_role_assignment" "fd_contributor" { - scope = azurerm_cdn_frontdoor_profile.this.id - role_definition_name = "CDN Profile Contributor" - principal_id = var.admin_identity_principal_id -} -``` - -### Private Endpoint - -Front Door Premium supports **Private Link origins** -- connecting to backends via private endpoints: - -```hcl -# Premium tier required for Private Link origins -resource "azurerm_cdn_frontdoor_origin" "private" { - name = "private-origin" - cdn_frontdoor_origin_group_id = azurerm_cdn_frontdoor_origin_group.this.id - enabled = true - - host_name = var.private_origin_hostname - origin_host_header = var.private_origin_hostname - certificate_name_check_enabled = true - priority = 1 - weight = 1000 - - private_link { - location = var.location - private_link_target_id = var.app_service_id # or other PL-supported resource - request_message = "Front Door Private Link" - target_type = "sites" # Depends on origin type - } -} -``` - -**Note:** Private Link origins require manual approval on the backend resource. The `request_message` appears in the backend's private endpoint connections for approval. - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the Front Door profile') -param name string - -@description('Origin hostname (e.g., myapp.azurewebsites.net)') -param originHostname string - -@description('Tags to apply') -param tags object = {} - -resource profile 'Microsoft.Cdn/profiles@2024-02-01' = { - name: name - location: 'global' - tags: tags - sku: { - name: 'Standard_AzureFrontDoor' - } -} - -resource endpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { - parent: profile - name: 'default-endpoint' - location: 'global' - properties: { - enabledState: 'Enabled' - } -} - -resource originGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { - parent: profile - name: 'default-origin-group' - properties: { - loadBalancingSettings: { - sampleSize: 4 - successfulSamplesRequired: 3 - } - healthProbeSettings: { - probePath: '/health' - probeProtocol: 'Https' - probeRequestType: 'HEAD' - probeIntervalInSeconds: 30 - } - } -} - -resource origin 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { - parent: originGroup - name: 'primary' - properties: { - hostName: originHostname - httpPort: 80 - httpsPort: 443 - originHostHeader: originHostname - priority: 1 - weight: 1000 - enabledState: 'Enabled' - enforceCertificateNameCheck: true - } -} - -resource route 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { - parent: endpoint - name: 'default-route' - properties: { - originGroup: { - id: originGroup.id - } - supportedProtocols: ['Http', 'Https'] - patternsToMatch: ['/*'] - forwardingProtocol: 'HttpsOnly' - httpsRedirect: 'Enabled' - cacheConfiguration: { - queryStringCachingBehavior: 'IgnoreQueryString' - compressionSettings: { - isCompressionEnabled: true - contentTypesToCompress: [ - 'text/html' - 'text/css' - 'application/javascript' - 'application/json' - ] - } - } - } -} - -output endpointHostname string = endpoint.properties.hostName -output profileId string = profile.id -``` - -### RBAC Assignment - -No data-plane RBAC needed -- management-plane only. - -## Application Code - -Front Door is transparent to application code -- requests are proxied without modification. Key integration points: - -### Health Probe Endpoint - -```python -# Python (FastAPI) -- health endpoint for Front Door probes -from fastapi import FastAPI - -app = FastAPI() - -@app.get("/health") -async def health(): - return {"status": "healthy"} -``` - -### Extracting Client IP Behind Front Door - -```python -# The real client IP is in X-Forwarded-For header -from fastapi import Request - -@app.get("/api/info") -async def info(request: Request): - client_ip = request.headers.get("X-Azure-ClientIP") # Front Door-specific - forwarded_for = request.headers.get("X-Forwarded-For") - return {"client_ip": client_ip, "forwarded_for": forwarded_for} -``` - -### Restricting Origin to Front Door Only - -```python -# Verify requests come from Front Door using X-Azure-FDID header -FRONT_DOOR_ID = "" - -@app.middleware("http") -async def verify_front_door(request, call_next): - fd_id = request.headers.get("X-Azure-FDID") - if fd_id != FRONT_DOOR_ID: - return JSONResponse(status_code=403, content={"error": "Direct access forbidden"}) - return await call_next(request) -``` - -## Common Pitfalls - -1. **DNS CNAME validation required for custom domains** -- Must create a `_dnsauth` TXT record or CNAME before Front Door accepts the domain. Propagation delays cause frustrating failures. -2. **WAF policy name cannot contain hyphens** -- Policy names must be alphanumeric only. Use `replace()` in Terraform/Bicep to strip hyphens from the base name. -3. **Caching API responses accidentally** -- Default route caches everything. Add a separate route for `/api/*` with caching disabled, or use `Cache-Control: no-store` headers. -4. **Origin host header mismatch** -- If the origin hostname differs from the custom domain, App Service may reject the request. Set `origin_host_header` to match the backend's expected hostname. -5. **Private Link approval is manual** -- Premium tier Private Link origins require manual approval on the backend. Automate with `az network private-endpoint-connection approve` in deployment scripts. -6. **Standard vs Premium tier confusion** -- Standard = CDN + routing. Premium = CDN + routing + WAF + Private Link origins. WAF is Premium-only. -7. **Long propagation times** -- Profile and endpoint changes can take 10-20 minutes to propagate globally. Plan for this in deployment pipelines. - -## Production Backlog Items - -- [ ] Upgrade to Premium tier for WAF and Private Link origins -- [ ] Enable WAF with Microsoft_DefaultRuleSet and BotManagerRuleSet -- [ ] Configure custom domain with managed SSL certificate -- [ ] Restrict backend origins to accept traffic only from Front Door (X-Azure-FDID validation) -- [ ] Enable Private Link origins for all backends -- [ ] Configure rate limiting rules in WAF policy -- [ ] Set up geo-filtering rules if needed -- [ ] Enable diagnostic logging to Log Analytics -- [ ] Configure custom error pages (403, 502, 503) -- [ ] Implement cache purge automation for deployments +--- +service_namespace: Microsoft.Network/frontDoors +display_name: Azure Front Door (Classic) +--- + +# Azure Front Door +> Global load balancer and CDN with built-in WAF, SSL offloading, and intelligent traffic routing for web applications. + +## When to Use + +- **Global traffic distribution** -- route users to the nearest backend across regions +- **Web Application Firewall (WAF)** -- DDoS protection, bot mitigation, OWASP rule sets +- **Custom domains with managed SSL** -- automated certificate provisioning and renewal +- **CDN for static assets** -- cache static content at edge locations worldwide +- **Multi-backend failover** -- health probes with automatic failover between origins + +Choose Front Door over Azure Application Gateway when you need global (multi-region) distribution or CDN capabilities. Choose Application Gateway for single-region, VNet-internal load balancing with more granular L7 routing. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Tier | Standard | CDN + basic routing; Premium adds WAF + Private Link | +| WAF | Disabled (POC) | Enable with managed rule sets for production | +| Caching | Enabled for static | Cache CSS/JS/images; bypass for API routes | +| Origin response timeout | 60 seconds | Default; increase for long-running APIs | +| Health probe | Enabled | HEAD requests every 30 seconds | +| Session affinity | Disabled | Stateless backends preferred for POC | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "profile" { + type = "Microsoft.Cdn/profiles@2024-02-01" + name = var.name + location = "global" + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_AzureFrontDoor" # or "Premium_AzureFrontDoor" + } + } + + tags = var.tags + + response_export_values = ["*"] +} + +resource "azapi_resource" "endpoint" { + type = "Microsoft.Cdn/profiles/afdEndpoints@2024-02-01" + name = var.endpoint_name + location = "global" + parent_id = azapi_resource.profile.id + + body = { + properties = { + enabledState = "Enabled" + } + } +} + +resource "azapi_resource" "origin_group" { + type = "Microsoft.Cdn/profiles/originGroups@2024-02-01" + name = "default-origin-group" + parent_id = azapi_resource.profile.id + + body = { + properties = { + loadBalancingSettings = { + sampleSize = 4 + successfulSamplesRequired = 3 + } + healthProbeSettings = { + probePath = "/health" + probeProtocol = "Https" + probeRequestType = "HEAD" + probeIntervalInSeconds = 30 + } + } + } +} + +resource "azapi_resource" "origin" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "primary-origin" + parent_id = azapi_resource.origin_group.id + + body = { + properties = { + hostName = var.origin_hostname # e.g., "myapp.azurewebsites.net" + httpPort = 80 + httpsPort = 443 + originHostHeader = var.origin_hostname + enforceCertificateNameCheck = true + priority = 1 + weight = 1000 + enabledState = "Enabled" + } + } +} + +resource "azapi_resource" "route" { + type = "Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01" + name = "default-route" + parent_id = azapi_resource.endpoint.id + + body = { + properties = { + originGroup = { + id = azapi_resource.origin_group.id + } + supportedProtocols = ["Http", "Https"] + patternsToMatch = ["/*"] + forwardingProtocol = "HttpsOnly" + httpsRedirect = "Enabled" + cacheConfiguration = { + queryStringCachingBehavior = "IgnoreQueryString" + compressionSettings = { + isCompressionEnabled = true + contentTypesToCompress = [ + "text/html", "text/css", "application/javascript", + "application/json", "image/svg+xml" + ] + } + } + } + } +} +``` + +### WAF Policy (Premium tier) + +```hcl +resource "azapi_resource" "waf_policy" { + type = "Microsoft.Network/FrontDoorWebApplicationFirewallPolicies@2024-02-01" + name = replace(var.name, "-", "") # No hyphens allowed + location = "global" + parent_id = var.resource_group_id + + body = { + sku = { + name = "Premium_AzureFrontDoor" + } + properties = { + policySettings = { + mode = "Prevention" + } + managedRules = { + managedRuleSets = [ + { + ruleSetType = "Microsoft_DefaultRuleSet" + ruleSetVersion = "2.1" + ruleSetAction = "Block" + }, + { + ruleSetType = "Microsoft_BotManagerRuleSet" + ruleSetVersion = "1.1" + ruleSetAction = "Block" + } + ] + } + } + } + + tags = var.tags +} + +resource "azapi_resource" "security_policy" { + type = "Microsoft.Cdn/profiles/securityPolicies@2024-02-01" + name = "waf-policy" + parent_id = azapi_resource.profile.id + + body = { + properties = { + parameters = { + type = "WebApplicationFirewall" + wafPolicy = { + id = azapi_resource.waf_policy.id + } + associations = [ + { + domains = [ + { + id = azapi_resource.endpoint.id + } + ] + patternsToMatch = ["/*"] + } + ] + } + } + } +} +``` + +### RBAC Assignment + +Front Door is typically managed by infrastructure teams. No data-plane RBAC needed -- traffic flows through without authentication at the Front Door level. + +```hcl +# CDN Profile Contributor -- manage Front Door configuration +resource "azapi_resource" "fd_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.profile.id}-cdn-contributor") + parent_id = azapi_resource.profile.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/ec156ff8-a8d1-4d15-830c-5b80698ca432" + principalId = var.admin_identity_principal_id + } + } +} +``` + +### Private Endpoint + +Front Door Premium supports **Private Link origins** -- connecting to backends via private endpoints: + +```hcl +# Premium tier required for Private Link origins +resource "azapi_resource" "private_origin" { + type = "Microsoft.Cdn/profiles/originGroups/origins@2024-02-01" + name = "private-origin" + parent_id = azapi_resource.origin_group.id + + body = { + properties = { + hostName = var.private_origin_hostname + originHostHeader = var.private_origin_hostname + enforceCertificateNameCheck = true + priority = 1 + weight = 1000 + enabledState = "Enabled" + sharedPrivateLinkResource = { + privateLink = { + id = var.app_service_id # or other PL-supported resource + } + privateLinkLocation = var.location + requestMessage = "Front Door Private Link" + groupId = "sites" # Depends on origin type + } + } + } +} +``` + +**Note:** Private Link origins require manual approval on the backend resource. The `request_message` appears in the backend's private endpoint connections for approval. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Front Door profile') +param name string + +@description('Origin hostname (e.g., myapp.azurewebsites.net)') +param originHostname string + +@description('Tags to apply') +param tags object = {} + +resource profile 'Microsoft.Cdn/profiles@2024-02-01' = { + name: name + location: 'global' + tags: tags + sku: { + name: 'Standard_AzureFrontDoor' + } +} + +resource endpoint 'Microsoft.Cdn/profiles/afdEndpoints@2024-02-01' = { + parent: profile + name: 'default-endpoint' + location: 'global' + properties: { + enabledState: 'Enabled' + } +} + +resource originGroup 'Microsoft.Cdn/profiles/originGroups@2024-02-01' = { + parent: profile + name: 'default-origin-group' + properties: { + loadBalancingSettings: { + sampleSize: 4 + successfulSamplesRequired: 3 + } + healthProbeSettings: { + probePath: '/health' + probeProtocol: 'Https' + probeRequestType: 'HEAD' + probeIntervalInSeconds: 30 + } + } +} + +resource origin 'Microsoft.Cdn/profiles/originGroups/origins@2024-02-01' = { + parent: originGroup + name: 'primary' + properties: { + hostName: originHostname + httpPort: 80 + httpsPort: 443 + originHostHeader: originHostname + priority: 1 + weight: 1000 + enabledState: 'Enabled' + enforceCertificateNameCheck: true + } +} + +resource route 'Microsoft.Cdn/profiles/afdEndpoints/routes@2024-02-01' = { + parent: endpoint + name: 'default-route' + properties: { + originGroup: { + id: originGroup.id + } + supportedProtocols: ['Http', 'Https'] + patternsToMatch: ['/*'] + forwardingProtocol: 'HttpsOnly' + httpsRedirect: 'Enabled' + cacheConfiguration: { + queryStringCachingBehavior: 'IgnoreQueryString' + compressionSettings: { + isCompressionEnabled: true + contentTypesToCompress: [ + 'text/html' + 'text/css' + 'application/javascript' + 'application/json' + ] + } + } + } +} + +output endpointHostname string = endpoint.properties.hostName +output profileId string = profile.id +``` + +### RBAC Assignment + +No data-plane RBAC needed -- management-plane only. + +## Application Code + +Front Door is transparent to application code -- requests are proxied without modification. Key integration points: + +### Health Probe Endpoint + +```python +# Python (FastAPI) -- health endpoint for Front Door probes +from fastapi import FastAPI + +app = FastAPI() + +@app.get("/health") +async def health(): + return {"status": "healthy"} +``` + +### Extracting Client IP Behind Front Door + +```python +# The real client IP is in X-Forwarded-For header +from fastapi import Request + +@app.get("/api/info") +async def info(request: Request): + client_ip = request.headers.get("X-Azure-ClientIP") # Front Door-specific + forwarded_for = request.headers.get("X-Forwarded-For") + return {"client_ip": client_ip, "forwarded_for": forwarded_for} +``` + +### Restricting Origin to Front Door Only + +```python +# Verify requests come from Front Door using X-Azure-FDID header +FRONT_DOOR_ID = "" + +@app.middleware("http") +async def verify_front_door(request, call_next): + fd_id = request.headers.get("X-Azure-FDID") + if fd_id != FRONT_DOOR_ID: + return JSONResponse(status_code=403, content={"error": "Direct access forbidden"}) + return await call_next(request) +``` + +## Common Pitfalls + +1. **DNS CNAME validation required for custom domains** -- Must create a `_dnsauth` TXT record or CNAME before Front Door accepts the domain. Propagation delays cause frustrating failures. +2. **WAF policy name cannot contain hyphens** -- Policy names must be alphanumeric only. Use `replace()` in Terraform/Bicep to strip hyphens from the base name. +3. **Caching API responses accidentally** -- Default route caches everything. Add a separate route for `/api/*` with caching disabled, or use `Cache-Control: no-store` headers. +4. **Origin host header mismatch** -- If the origin hostname differs from the custom domain, App Service may reject the request. Set `origin_host_header` to match the backend's expected hostname. +5. **Private Link approval is manual** -- Premium tier Private Link origins require manual approval on the backend. Automate with `az network private-endpoint-connection approve` in deployment scripts. +6. **Standard vs Premium tier confusion** -- Standard = CDN + routing. Premium = CDN + routing + WAF + Private Link origins. WAF is Premium-only. +7. **Long propagation times** -- Profile and endpoint changes can take 10-20 minutes to propagate globally. Plan for this in deployment pipelines. + +## Production Backlog Items + +- [ ] Upgrade to Premium tier for WAF and Private Link origins +- [ ] Enable WAF with Microsoft_DefaultRuleSet and BotManagerRuleSet +- [ ] Configure custom domain with managed SSL certificate +- [ ] Restrict backend origins to accept traffic only from Front Door (X-Azure-FDID validation) +- [ ] Enable Private Link origins for all backends +- [ ] Configure rate limiting rules in WAF policy +- [ ] Set up geo-filtering rules if needed +- [ ] Enable diagnostic logging to Log Analytics +- [ ] Configure custom error pages (403, 502, 503) +- [ ] Implement cache purge automation for deployments diff --git a/azext_prototype/knowledge/services/iot-hub-consumer-group.md b/azext_prototype/knowledge/services/iot-hub-consumer-group.md new file mode 100644 index 0000000..ffd0d94 --- /dev/null +++ b/azext_prototype/knowledge/services/iot-hub-consumer-group.md @@ -0,0 +1,139 @@ +--- +service_namespace: Microsoft.Devices/IotHubs/eventHubEndpoints/ConsumerGroups +display_name: IoT Hub Consumer Group +depends_on: + - Microsoft.Devices/IotHubs +--- + +# IoT Hub Consumer Group + +> A consumer group on the IoT Hub's built-in Event Hub-compatible endpoint, enabling multiple downstream readers to independently process device-to-cloud messages. + +## When to Use +- Each application or processing pipeline reading from IoT Hub needs its own consumer group +- The default `$Default` consumer group should not be shared across applications +- Separate consumer groups for real-time analytics, storage archival, and alerting pipelines +- Required when multiple Azure Stream Analytics jobs or Azure Functions read from the same IoT Hub + +## POC Defaults +- **Endpoint name**: `events` (the built-in Event Hub-compatible endpoint) +- **Consumer group name**: Application-specific (e.g., `analytics`, `storage-writer`) +- **Default**: `$Default` exists automatically — create additional groups as needed + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "iot_consumer_group" { + type = "Microsoft.Devices/IotHubs/eventHubEndpoints/ConsumerGroups@2023-06-30" + name = var.consumer_group_name + parent_id = "${azapi_resource.iot_hub.id}/eventHubEndpoints/events" + + body = { + properties = { + name = var.consumer_group_name + } + } +} +``` + +### RBAC Assignment +```hcl +# Consumer group access inherits from the IoT Hub RBAC. +# IoT Hub Data Reader role grants read access to the events endpoint. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param consumerGroupName string + +resource consumerGroup 'Microsoft.Devices/IotHubs/eventHubEndpoints/ConsumerGroups@2023-06-30' = { + // Note: parent chain is IotHub > eventHubEndpoints > ConsumerGroups + name: '${iotHub.name}/events/${consumerGroupName}' + properties: {} +} +``` + +## Application Code + +### Python +```python +from azure.eventhub import EventHubConsumerClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +# IoT Hub's built-in endpoint is Event Hub-compatible +consumer = EventHubConsumerClient( + fully_qualified_namespace=".servicebus.windows.net", + eventhub_name="", + consumer_group=consumer_group_name, + credential=credential +) + +async def on_event(partition_context, event): + device_id = event.system_properties[b"iothub-connection-device-id"].decode() + print(f"Device: {device_id}, Data: {event.body_as_str()}") + await partition_context.update_checkpoint(event) + +async with consumer: + await consumer.receive(on_event=on_event) +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Messaging.EventHubs.Consumer; + +var credential = new DefaultAzureCredential(); +// Use the IoT Hub's Event Hub-compatible endpoint +var consumer = new EventHubConsumerClient( + consumerGroupName, + ".servicebus.windows.net", + "", + credential); + +await foreach (var partitionEvent in consumer.ReadEventsAsync()) +{ + var deviceId = partitionEvent.Data.SystemProperties["iothub-connection-device-id"]; + Console.WriteLine($"Device: {deviceId}, Data: {partitionEvent.Data.EventBody}"); +} +``` + +### Node.js +```typescript +import { EventHubConsumerClient } from "@azure/event-hubs"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const consumer = new EventHubConsumerClient( + consumerGroupName, + ".servicebus.windows.net", + "", + credential +); + +const subscription = consumer.subscribe({ + processEvents: async (events) => { + for (const event of events) { + const deviceId = event.systemProperties["iothub-connection-device-id"]; + console.log(`Device: ${deviceId}, Data: ${event.body}`); + } + }, + processError: async (err) => console.error(err), +}); +``` + +## Common Pitfalls +- **Parent path includes 'events'**: The parent resource ID must include `/eventHubEndpoints/events`. Omitting this segment causes a 404 error. +- **$Default is shared**: The default consumer group is shared by all readers. Create dedicated consumer groups to avoid checkpoint conflicts. +- **Max consumer groups varies by tier**: Free/Basic: 2, S1: 10, S2/S3: up to 20. Exceeding the limit fails with a quota error. +- **Event Hub SDK, not IoT SDK**: Reading from the built-in endpoint uses the Event Hubs SDK, not the IoT Hub SDK. The IoT Hub SDK is for device management. +- **Checkpoint storage needed**: Like Event Hubs, reliable processing requires checkpoint storage in Azure Blob Storage. + +## Production Backlog Items +- Checkpoint storage configuration for reliable offset management +- Consumer group per downstream service (analytics, archival, alerting) +- Consumer lag monitoring and alerting +- Message enrichment rules on the IoT Hub for simplified downstream processing diff --git a/azext_prototype/knowledge/services/iot-hub.md b/azext_prototype/knowledge/services/iot-hub.md new file mode 100644 index 0000000..3a06b4c --- /dev/null +++ b/azext_prototype/knowledge/services/iot-hub.md @@ -0,0 +1,349 @@ +--- +service_namespace: Microsoft.Devices/IotHubs +display_name: Azure IoT Hub +--- + +# Azure IoT Hub +> Managed service for bi-directional communication between IoT applications and devices, with device management, security, and message routing at scale. + +## When to Use + +- **Device telemetry ingestion** -- collecting data from thousands to millions of IoT devices +- **Device management** -- provisioning, monitoring, and updating device firmware and configuration +- **Cloud-to-device messaging** -- sending commands, configuration updates, or notifications to devices +- **Edge computing** -- deploying workloads to IoT Edge devices with Azure IoT Edge integration +- **Digital twins** -- integrating with Azure Digital Twins for spatial intelligence scenarios + +Choose IoT Hub over Event Hubs when you need device identity management, per-device authentication, cloud-to-device messaging, or device twins. Choose Event Hubs for simple high-throughput telemetry ingestion without device management. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | S1 (Standard) | Free tier (F1) limited to 8K messages/day; S1 for realistic POC | +| Units | 1 | Each S1 unit = 400K messages/day | +| Partitions | 4 | Default; sufficient for POC throughput | +| Message retention | 1 day | Minimum; increase for replay scenarios | +| Device authentication | Symmetric key | SAS tokens for POC; X.509 certificates for production | +| Cloud-to-device | Enabled | Built-in with Standard tier | +| File upload | Optional | Requires linked storage account | +| Public network access | Disabled (unless user overrides) | Flag private endpoint as production backlog item | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "iot_hub" { + type = "Microsoft.Devices/IotHubs@2023-06-30" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [var.managed_identity_id] + } + + body = { + sku = { + name = "S1" + capacity = 1 + } + properties = { + publicNetworkAccess = "Disabled" # Unless told otherwise, disabled per governance policy + minTlsVersion = "1.2" + disableLocalAuth = false # Devices use SAS tokens; disable for X.509-only + eventHubEndpoints = { + events = { + retentionTimeInDays = 1 + partitionCount = 4 + } + } + routing = { + fallbackRoute = { + name = "fallback" + source = "DeviceMessages" + condition = "true" + endpointNames = ["events"] + isEnabled = true + } + } + } + } + + tags = var.tags + + response_export_values = ["properties.hostName", "properties.eventHubEndpoints.events"] +} +``` + +### Consumer Group + +```hcl +resource "azapi_resource" "consumer_group" { + type = "Microsoft.Devices/IotHubs/eventHubEndpoints/ConsumerGroups@2023-06-30" + name = var.consumer_group_name + parent_id = "${azapi_resource.iot_hub.id}/eventHubEndpoints/events" + + body = { + properties = { + name = var.consumer_group_name + } + } +} +``` + +### Message Route to Storage + +```hcl +resource "azapi_resource" "storage_endpoint" { + type = "Microsoft.Devices/IotHubs@2023-06-30" + name = azapi_resource.iot_hub.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + routing = { + endpoints = { + storageContainers = [ + { + name = "storage-endpoint" + connectionString = "" # Use identity-based when possible + containerName = var.container_name + fileNameFormat = "{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}" + batchFrequencyInSeconds = 300 + maxChunkSizeInBytes = 314572800 + encoding = "JSON" + authenticationType = "identityBased" + endpointUri = "https://${var.storage_account_name}.blob.core.windows.net" + identity = { + userAssignedIdentity = var.managed_identity_id + } + } + ] + } + routes = [ + { + name = "telemetry-to-storage" + source = "DeviceMessages" + condition = "true" + endpointNames = ["storage-endpoint"] + isEnabled = true + } + ] + fallbackRoute = { + name = "fallback" + source = "DeviceMessages" + condition = "true" + endpointNames = ["events"] + isEnabled = true + } + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# IoT Hub Data Contributor -- read/write device data, invoke direct methods +resource "azapi_resource" "iothub_data_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.iot_hub.id}${var.managed_identity_principal_id}iothub-data-contributor") + parent_id = azapi_resource.iot_hub.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4fc6c259-987e-4a07-842e-c321cc9d413f" # IoT Hub Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant IoT Hub's identity access to storage for message routing +resource "azapi_resource" "storage_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}${var.managed_identity_principal_id}storage-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +RBAC role IDs: +- IoT Hub Data Contributor: `4fc6c259-987e-4a07-842e-c321cc9d413f` +- IoT Hub Data Reader: `b447c946-2db7-41ec-983d-d8bf3b1c77e3` +- IoT Hub Registry Contributor: `4ea46cd5-c1b2-4a8e-910b-273211f9ce47` +- IoT Hub Twin Contributor: `494bdba2-168f-4f31-a0a1-191d2f7c028c` + +### Private Endpoint + +```hcl +resource "azapi_resource" "iot_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.iot_hub.id + groupIds = ["iotHub"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "iot_pe_dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.iot_private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zone: `privatelink.azure-devices.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the IoT Hub') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Managed identity resource ID') +param managedIdentityId string + +@description('Tags to apply') +param tags object = {} + +resource iotHub 'Microsoft.Devices/IotHubs@2023-06-30' = { + name: name + location: location + tags: tags + identity: { + type: 'UserAssigned' + userAssignedIdentities: { + '${managedIdentityId}': {} + } + } + sku: { + name: 'S1' + capacity: 1 + } + properties: { + publicNetworkAccess: 'Disabled' + minTlsVersion: '1.2' + eventHubEndpoints: { + events: { + retentionTimeInDays: 1 + partitionCount: 4 + } + } + routing: { + fallbackRoute: { + name: 'fallback' + source: 'DeviceMessages' + condition: 'true' + endpointNames: [ + 'events' + ] + isEnabled: true + } + } + } +} + +output id string = iotHub.id +output name string = iotHub.name +output hostName string = iotHub.properties.hostName +output eventHubEndpoint string = iotHub.properties.eventHubEndpoints.events.endpoint +``` + +### RBAC Assignment + +```bicep +@description('Principal ID for IoT Hub data access') +param principalId string + +var iotHubDataContributorRoleId = '4fc6c259-987e-4a07-842e-c321cc9d413f' + +resource iotDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(iotHub.id, principalId, iotHubDataContributorRoleId) + scope: iotHub + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', iotHubDataContributorRoleId) + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Free tier (F1) message limits | Only 8K messages/day; quickly exhausted | Use S1 for realistic POC workloads | +| Message size limit (256 KB) | Large payloads rejected | Use file upload for large data; keep telemetry messages small | +| Partition count is immutable | Cannot change after creation | Plan partition count based on expected throughput | +| Device twin size limit (8 KB) | Cannot store large device state | Use desired/reported properties sparingly; offload to external store | +| Missing consumer group | Multiple readers interfere with each other | Create dedicated consumer groups per downstream service | +| SAS token expiration | Devices disconnect and cannot reconnect | Implement token refresh logic; use X.509 for production | +| Throttling on device operations | Bulk device provisioning fails | Use Device Provisioning Service for at-scale onboarding | +| Built-in endpoint retention | Messages lost after retention period | Route messages to storage for long-term retention | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Private endpoint | P1 | Add private endpoint and disable public network access | +| X.509 certificate auth | P1 | Migrate from SAS tokens to X.509 certificates for device authentication | +| Device Provisioning Service | P2 | Enable zero-touch device provisioning at scale | +| Message routing | P2 | Configure routes to Storage, Event Hubs, or Service Bus for downstream processing | +| IoT Edge | P2 | Deploy edge modules for local processing and offline capability | +| Device Update | P3 | Configure Azure Device Update for OTA firmware updates | +| Monitoring and alerts | P2 | Set up alerts for connected devices, message throughput, and throttling | +| Diagnostic logging | P3 | Enable diagnostic logs and route to Log Analytics | +| IP filtering | P2 | Configure IP filter rules to restrict device connections by source IP | +| Disaster recovery | P3 | Configure manual failover to paired region for business continuity | diff --git a/azext_prototype/knowledge/services/key-vault-key.md b/azext_prototype/knowledge/services/key-vault-key.md new file mode 100644 index 0000000..53641c7 --- /dev/null +++ b/azext_prototype/knowledge/services/key-vault-key.md @@ -0,0 +1,138 @@ +--- +service_namespace: Microsoft.KeyVault/vaults/keys +display_name: Key Vault Key +depends_on: + - Microsoft.KeyVault/vaults +--- + +# Key Vault Key + +> A cryptographic key stored in Azure Key Vault. Used for encryption, signing, and wrapping operations — typically for customer-managed key (CMK) scenarios. + +## When to Use +- Customer-managed encryption keys for storage, SQL, Cosmos DB, or disk encryption +- Application-level encryption/decryption operations +- Digital signature verification + +## POC Defaults +- **Key type**: RSA (2048-bit) +- **Operations**: encrypt, decrypt, wrapKey, unwrapKey +- **Not typically needed for POC**: Service-managed keys are sufficient. Only create keys when CMK is a requirement. + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "kv_key" { + type = "Microsoft.KeyVault/vaults/keys@2023-07-01" + name = var.key_name + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + kty = "RSA" + keySize = 2048 + keyOps = ["encrypt", "decrypt", "wrapKey", "unwrapKey"] + } + } + + response_export_values = ["*"] +} +``` + +### RBAC Assignment +```hcl +# Key access is granted at the vault level via RBAC: +# Key Vault Crypto User (use keys): 12338af0-0e69-4776-bea7-57ae8d297424 +# Key Vault Crypto Officer (manage keys): 14b46e9e-c2b7-41b4-b07b-48a6ebf60603 +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param keyName string + +resource key 'Microsoft.KeyVault/vaults/keys@2023-07-01' = { + parent: keyVault + name: keyName + properties: { + kty: 'RSA' + keySize: 2048 + keyOps: ['encrypt', 'decrypt', 'wrapKey', 'unwrapKey'] + } +} + +output keyId string = key.id +output keyUri string = key.properties.keyUri +output keyUriWithVersion string = key.properties.keyUriWithVersion +``` + +## Application Code + +### Python +```python +from azure.keyvault.keys import KeyClient +from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +key_client = KeyClient(vault_url="https://.vault.azure.net/", credential=credential) + +key = key_client.get_key("my-key") +crypto_client = CryptographyClient(key.id, credential=credential) + +# Encrypt +result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, b"plaintext") +ciphertext = result.ciphertext + +# Decrypt +result = crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep, ciphertext) +plaintext = result.plaintext +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Security.KeyVault.Keys; +using Azure.Security.KeyVault.Keys.Cryptography; + +var credential = new DefaultAzureCredential(); +var keyClient = new KeyClient(new Uri("https://.vault.azure.net/"), credential); + +var key = await keyClient.GetKeyAsync("my-key"); +var cryptoClient = new CryptographyClient(key.Value.Id, credential); + +// Encrypt +var encrypted = await cryptoClient.EncryptAsync(EncryptionAlgorithm.RsaOaep, plaintext); +// Decrypt +var decrypted = await cryptoClient.DecryptAsync(EncryptionAlgorithm.RsaOaep, encrypted.Ciphertext); +``` + +### Node.js +```typescript +import { KeyClient, CryptographyClient } from "@azure/keyvault-keys"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const keyClient = new KeyClient("https://.vault.azure.net/", credential); + +const key = await keyClient.getKey("my-key"); +const cryptoClient = new CryptographyClient(key.id!, credential); + +// Encrypt +const encrypted = await cryptoClient.encrypt("RSA-OAEP", Buffer.from("plaintext")); +// Decrypt +const decrypted = await cryptoClient.decrypt("RSA-OAEP", encrypted.result); +``` + +## Common Pitfalls +- **Key type immutability**: Key type (RSA, EC) cannot be changed after creation. Create a new key if you need a different type. +- **Purge protection blocks recreation**: With purge protection enabled, deleted keys cannot be recreated with the same name until the retention period expires. +- **CMK rotation**: When rotating customer-managed keys, update all services that reference the key. Azure Storage handles this automatically; other services may not. + +## Production Backlog Items +- Automatic key rotation with rotation policy +- HSM-backed keys for higher security (Premium SKU or Managed HSM) +- Key expiration monitoring and alerting +- Separate keys per service for blast radius reduction diff --git a/azext_prototype/knowledge/services/key-vault-secret.md b/azext_prototype/knowledge/services/key-vault-secret.md new file mode 100644 index 0000000..e61008c --- /dev/null +++ b/azext_prototype/knowledge/services/key-vault-secret.md @@ -0,0 +1,129 @@ +--- +service_namespace: Microsoft.KeyVault/vaults/secrets +display_name: Key Vault Secret +depends_on: + - Microsoft.KeyVault/vaults +--- + +# Key Vault Secret + +> A named secret value stored in Azure Key Vault. Used for external credentials, connection strings, and configuration that cannot use managed identity. + +## When to Use +- Storing third-party API keys, external service credentials +- Connection strings for services that don't support managed identity (e.g., Redis connection strings, SignalR connection strings) +- Configuration values that must be rotatable without redeployment + +## POC Defaults +- **Content type**: `text/plain` for simple strings; `application/x-pkcs12` for certificates +- **Enabled**: true +- **Expiration**: Not set for POC (set rotation policy for production) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "kv_secret" { + type = "Microsoft.KeyVault/vaults/secrets@2023-07-01" + name = var.secret_name + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + value = var.secret_value + contentType = "text/plain" + } + } +} +``` + +### RBAC Assignment +```hcl +# Secret access is granted at the vault level via RBAC: +# Key Vault Secrets User (read): 4633458b-17de-408a-b874-0445c86b69e6 +# Key Vault Secrets Officer (read/write): b86a8fe4-44ce-4948-aee5-eccb2c155cd7 +# See the key-vault knowledge file for role assignment patterns. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param secretName string +@secure() +param secretValue string + +resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = { + parent: keyVault + name: secretName + properties: { + value: secretValue + contentType: 'text/plain' + } +} + +output secretUri string = secret.properties.secretUri +output secretName string = secret.name +``` + +## Application Code + +### Python +```python +from azure.keyvault.secrets import SecretClient +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +client = SecretClient(vault_url="https://.vault.azure.net/", credential=credential) + +# Read secret +secret = client.get_secret("my-secret") +print(secret.value) + +# Set secret +client.set_secret("my-secret", "new-value") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Security.KeyVault.Secrets; + +var credential = new DefaultAzureCredential(); +var client = new SecretClient(new Uri("https://.vault.azure.net/"), credential); + +// Read +KeyVaultSecret secret = await client.GetSecretAsync("my-secret"); +Console.WriteLine(secret.Value); + +// Set +await client.SetSecretAsync("my-secret", "new-value"); +``` + +### Node.js +```typescript +import { SecretClient } from "@azure/keyvault-secrets"; +import { DefaultAzureCredential } from "@azure/identity"; + +const credential = new DefaultAzureCredential(); +const client = new SecretClient("https://.vault.azure.net/", credential); + +// Read +const secret = await client.getSecret("my-secret"); +console.log(secret.value); + +// Set +await client.setSecret("my-secret", "new-value"); +``` + +## Common Pitfalls +- **Secret values in Terraform state**: Secret values stored via Terraform are visible in the state file. Mark the variable as `sensitive` and consider using a deploy-time script instead. +- **Soft delete and purge protection**: Deleted secrets remain recoverable for the retention period. You cannot reuse a secret name until purged or the retention period expires. +- **Secret URI vs value**: `secretUri` is the reference (safe to store in config). `value` is the actual secret (never log or output it). +- **Container Apps Key Vault references**: Use `secretRef` with the Key Vault secret URI, not direct environment variable values. + +## Production Backlog Items +- Automatic rotation policy with rotation event trigger +- Expiration dates with monitoring alerts +- Secret versioning and rollback procedures +- Access logging and anomaly detection via diagnostic settings diff --git a/azext_prototype/knowledge/services/key-vault.md b/azext_prototype/knowledge/services/key-vault.md index d765851..1e3702e 100644 --- a/azext_prototype/knowledge/services/key-vault.md +++ b/azext_prototype/knowledge/services/key-vault.md @@ -1,258 +1,335 @@ -# Azure Key Vault - -> Centralized secrets management, key management, and certificate management with hardware security module (HSM) backing. - -## When to Use -- Storing and managing application secrets, connection strings, and API keys -- Managing encryption keys for data-at-rest encryption across Azure services -- Provisioning and managing TLS/SSL certificates - -## POC Defaults -- **SKU**: Standard (HSM-backed keys available in Premium) -- **Authorization mode**: RBAC (`enable_rbac_authorization = true`) -- **Purge protection**: Enabled (required by many Azure services, cannot be disabled once enabled) -- **Soft delete**: Enabled with 90-day retention (enabled by default, cannot be disabled) - -## Terraform Patterns - -### Basic Resource -```hcl -data "azurerm_client_config" "current" {} - -resource "azurerm_key_vault" "this" { - name = var.key_vault_name - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - tenant_id = data.azurerm_client_config.current.tenant_id - sku_name = "standard" - enable_rbac_authorization = true # CRITICAL: Use RBAC, NOT access policies - purge_protection_enabled = true - soft_delete_retention_days = 90 - - network_acls { - bypass = "AzureServices" - default_action = "Allow" # Restrict to "Deny" for production - } - - tags = var.tags -} - -resource "azurerm_key_vault_secret" "example" { - name = "example-secret" - value = var.secret_value - key_vault_id = azurerm_key_vault.this.id - - depends_on = [azurerm_role_assignment.kv_secrets_officer_deployer] -} -``` - -### RBAC Assignment -```hcl -# Role IDs from service-registry.yaml: -# Key Vault Secrets User: 4633458b-17de-408a-b874-0445c86b69e6 -# Key Vault Secrets Officer: b86a8fe4-44ce-4948-aee5-eccb2c155cd7 -# Key Vault Administrator: 00482a5a-887f-4fb3-b363-3b7fe8e74483 - -# Grant the app's managed identity read access to secrets -resource "azurerm_role_assignment" "kv_secrets_user" { - scope = azurerm_key_vault.this.id - role_definition_name = "Key Vault Secrets User" - principal_id = azurerm_user_assigned_identity.this.principal_id -} - -# Grant the deploying principal write access to secrets (needed during deployment) -resource "azurerm_role_assignment" "kv_secrets_officer_deployer" { - scope = azurerm_key_vault.this.id - role_definition_name = "Key Vault Secrets Officer" - principal_id = data.azurerm_client_config.current.object_id -} -``` - -### Private Endpoint -```hcl -resource "azurerm_private_endpoint" "kv" { - name = "${var.key_vault_name}-pe" - location = azurerm_resource_group.this.location - resource_group_name = azurerm_resource_group.this.name - subnet_id = azurerm_subnet.private_endpoints.id - - private_service_connection { - name = "${var.key_vault_name}-psc" - private_connection_resource_id = azurerm_key_vault.this.id - is_manual_connection = false - subresource_names = ["vault"] - } - - private_dns_zone_group { - name = "default" - private_dns_zone_ids = [azurerm_private_dns_zone.kv.id] - } -} - -resource "azurerm_private_dns_zone" "kv" { - name = "privatelink.vaultcore.azure.net" - resource_group_name = azurerm_resource_group.this.name -} - -resource "azurerm_private_dns_zone_virtual_network_link" "kv" { - name = "kv-dns-link" - resource_group_name = azurerm_resource_group.this.name - private_dns_zone_name = azurerm_private_dns_zone.kv.name - virtual_network_id = azurerm_virtual_network.this.id -} -``` - -## Bicep Patterns - -### Basic Resource -```bicep -param keyVaultName string -param location string = resourceGroup().location -param tenantId string = subscription().tenantId -param tags object = {} - -resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { - name: keyVaultName - location: location - properties: { - tenantId: tenantId - sku: { - family: 'A' - name: 'standard' - } - enableRbacAuthorization: true // CRITICAL: Use RBAC, NOT access policies - enablePurgeProtection: true - enableSoftDelete: true - softDeleteRetentionInDays: 90 - networkAcls: { - bypass: 'AzureServices' - defaultAction: 'Allow' // Restrict to 'Deny' for production - } - } - tags: tags -} - -resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = { - parent: keyVault - name: 'example-secret' - properties: { - value: secretValue - } -} - -@secure() -param secretValue string - -output keyVaultUri string = keyVault.properties.vaultUri -output keyVaultId string = keyVault.id -``` - -### RBAC Assignment -```bicep -param principalId string - -// Key Vault Secrets User — read secrets -var secretsUserRoleId = '4633458b-17de-408a-b874-0445c86b69e6' - -resource secretsUserRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(keyVault.id, principalId, secretsUserRoleId) - scope: keyVault - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', secretsUserRoleId) - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -### Python -```python -from azure.identity import DefaultAzureCredential -from azure.keyvault.secrets import SecretClient - -credential = DefaultAzureCredential() -client = SecretClient( - vault_url="https://.vault.azure.net/", - credential=credential -) - -# Get a secret -secret = client.get_secret("example-secret") -print(f"Secret value: {secret.value}") - -# Set a secret -client.set_secret("new-secret", "secret-value") - -# List secrets (metadata only, not values) -for secret_properties in client.list_properties_of_secrets(): - print(f"Secret name: {secret_properties.name}") -``` - -### C# -```csharp -using Azure.Identity; -using Azure.Security.KeyVault.Secrets; - -var credential = new DefaultAzureCredential(); -var client = new SecretClient( - vaultUri: new Uri("https://.vault.azure.net/"), - credential: credential -); - -// Get a secret -KeyVaultSecret secret = await client.GetSecretAsync("example-secret"); -Console.WriteLine($"Secret value: {secret.Value}"); - -// Set a secret -await client.SetSecretAsync("new-secret", "secret-value"); - -// List secrets (metadata only, not values) -await foreach (SecretProperties secretProperties in client.GetPropertiesOfSecretsAsync()) -{ - Console.WriteLine($"Secret name: {secretProperties.Name}"); -} -``` - -### Node.js -```typescript -import { DefaultAzureCredential } from "@azure/identity"; -import { SecretClient } from "@azure/keyvault-secrets"; - -const credential = new DefaultAzureCredential(); -const client = new SecretClient( - "https://.vault.azure.net/", - credential -); - -// Get a secret -const secret = await client.getSecret("example-secret"); -console.log(`Secret value: ${secret.value}`); - -// Set a secret -await client.setSecret("new-secret", "secret-value"); - -// List secrets (metadata only, not values) -for await (const secretProperties of client.listPropertiesOfSecrets()) { - console.log(`Secret name: ${secretProperties.name}`); -} -``` - -## Common Pitfalls -- **Using access policies instead of RBAC**: Always set `enable_rbac_authorization = true`. Access policies are the legacy model and do not support fine-grained, identity-based control. -- **Deployer cannot write secrets**: When using RBAC mode, the Terraform/Bicep deploying principal needs the "Key Vault Secrets Officer" role to create secrets during deployment. Without this, `azurerm_key_vault_secret` resources will fail with 403. -- **Purge protection is irreversible**: Once `purge_protection_enabled = true` is set, it cannot be turned off. Deleted vaults/secrets remain for the full retention period. -- **Soft-deleted vault name collision**: A deleted vault still occupies its name for the retention period. Use `az keyvault list-deleted` to check for name conflicts. -- **Secret rotation not automatic**: Key Vault stores secrets but does not rotate them. Rotation requires Azure Function or Event Grid integration. -- **Network ACLs timing**: When setting `default_action = "Deny"`, ensure all required IPs and VNets are whitelisted first, or the deployer will lock itself out. - -## Production Backlog Items -- HSM-backed keys (Premium SKU) for regulatory compliance -- Network ACLs with default deny and explicit allow rules -- Diagnostic settings for audit logging (log all secret access) -- Key rotation policy with automated rotation via Event Grid -- Certificate management with auto-renewal -- Private endpoint with DNS integration -- Backup and disaster recovery procedures -- Integration with Azure Policy for compliance enforcement +--- +service_namespace: Microsoft.KeyVault/vaults +display_name: Azure Key Vault +--- + +# Azure Key Vault + +> Centralized secrets management, key management, and certificate management with hardware security module (HSM) backing. + +## When to Use +- Storing and managing application secrets, connection strings, and API keys +- Managing encryption keys for data-at-rest encryption across Azure services +- Provisioning and managing TLS/SSL certificates + +## POC Defaults +- **SKU**: Standard (HSM-backed keys available in Premium) +- **Authorization mode**: RBAC (`enable_rbac_authorization = true`) +- **Purge protection**: Enabled (required by many Azure services, cannot be disabled once enabled) +- **Soft delete**: Enabled with 90-day retention (enabled by default, cannot be disabled) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "key_vault" { + type = "Microsoft.KeyVault/vaults@2023-07-01" + name = var.key_vault_name + location = azapi_resource.resource_group.output.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + tenantId = var.tenant_id + sku = { + family = "A" + name = "standard" + } + enableRbacAuthorization = true # CRITICAL: Use RBAC, NOT access policies + enablePurgeProtection = true + enableSoftDelete = true + softDeleteRetentionInDays = 90 + networkAcls = { + bypass = "AzureServices" + defaultAction = "Allow" # Restrict to "Deny" for production + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} + +resource "azapi_resource" "key_vault_secret" { + type = "Microsoft.KeyVault/vaults/secrets@2023-07-01" + name = "example-secret" + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + value = var.secret_value + } + } + + depends_on = [azapi_resource.kv_secrets_officer_deployer] +} +``` + +### RBAC Assignment +```hcl +# Role IDs from service-registry.yaml: +# Key Vault Secrets User: 4633458b-17de-408a-b874-0445c86b69e6 +# Key Vault Secrets Officer: b86a8fe4-44ce-4948-aee5-eccb2c155cd7 +# Key Vault Administrator: 00482a5a-887f-4fb3-b363-3b7fe8e74483 + +# Grant the app's managed identity read access to secrets +resource "azapi_resource" "kv_secrets_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${azapi_resource.key_vault.id}-${azapi_resource.user_assigned_identity.output.properties.principalId}-4633458b-17de-408a-b874-0445c86b69e6") + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" + principalId = azapi_resource.user_assigned_identity.output.properties.principalId + principalType = "ServicePrincipal" + } + } +} + +# Grant the deploying principal write access to secrets (needed during deployment) +resource "azapi_resource" "kv_secrets_officer_deployer" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("sha1", "${azapi_resource.key_vault.id}-${var.deployer_object_id}-b86a8fe4-44ce-4948-aee5-eccb2c155cd7") + parent_id = azapi_resource.key_vault.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/b86a8fe4-44ce-4948-aee5-eccb2c155cd7" + principalId = var.deployer_object_id + principalType = "User" + } + } +} +``` + +### Private Endpoint +```hcl +resource "azapi_resource" "kv_private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "${var.key_vault_name}-pe" + location = azapi_resource.resource_group.output.location + parent_id = azapi_resource.resource_group.id + + body = { + properties = { + subnet = { + id = azapi_resource.private_endpoints_subnet.id + } + privateLinkServiceConnections = [ + { + name = "${var.key_vault_name}-psc" + properties = { + privateLinkServiceId = azapi_resource.key_vault.id + groupIds = ["vault"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "kv_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "privatelink.vaultcore.azure.net" + location = "global" + parent_id = azapi_resource.resource_group.id + + tags = var.tags +} + +resource "azapi_resource" "kv_dns_zone_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "kv-dns-link" + location = "global" + parent_id = azapi_resource.kv_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = azapi_resource.virtual_network.id + } + registrationEnabled = false + } + } + + tags = var.tags +} + +resource "azapi_resource" "kv_pe_dns_zone_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "default" + parent_id = azapi_resource.kv_private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = azapi_resource.kv_dns_zone.id + } + } + ] + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param keyVaultName string +param location string = resourceGroup().location +param tenantId string = subscription().tenantId +param tags object = {} + +resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { + name: keyVaultName + location: location + properties: { + tenantId: tenantId + sku: { + family: 'A' + name: 'standard' + } + enableRbacAuthorization: true // CRITICAL: Use RBAC, NOT access policies + enablePurgeProtection: true + enableSoftDelete: true + softDeleteRetentionInDays: 90 + networkAcls: { + bypass: 'AzureServices' + defaultAction: 'Allow' // Restrict to 'Deny' for production + } + } + tags: tags +} + +resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = { + parent: keyVault + name: 'example-secret' + properties: { + value: secretValue + } +} + +@secure() +param secretValue string + +output keyVaultUri string = keyVault.properties.vaultUri +output keyVaultId string = keyVault.id +``` + +### RBAC Assignment +```bicep +param principalId string + +// Key Vault Secrets User — read secrets +var secretsUserRoleId = '4633458b-17de-408a-b874-0445c86b69e6' + +resource secretsUserRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVault.id, principalId, secretsUserRoleId) + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', secretsUserRoleId) + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.keyvault.secrets import SecretClient + +credential = DefaultAzureCredential() +client = SecretClient( + vault_url="https://.vault.azure.net/", + credential=credential +) + +# Get a secret +secret = client.get_secret("example-secret") +print(f"Secret value: {secret.value}") + +# Set a secret +client.set_secret("new-secret", "secret-value") + +# List secrets (metadata only, not values) +for secret_properties in client.list_properties_of_secrets(): + print(f"Secret name: {secret_properties.name}") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.Security.KeyVault.Secrets; + +var credential = new DefaultAzureCredential(); +var client = new SecretClient( + vaultUri: new Uri("https://.vault.azure.net/"), + credential: credential +); + +// Get a secret +KeyVaultSecret secret = await client.GetSecretAsync("example-secret"); +Console.WriteLine($"Secret value: {secret.Value}"); + +// Set a secret +await client.SetSecretAsync("new-secret", "secret-value"); + +// List secrets (metadata only, not values) +await foreach (SecretProperties secretProperties in client.GetPropertiesOfSecretsAsync()) +{ + Console.WriteLine($"Secret name: {secretProperties.Name}"); +} +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { SecretClient } from "@azure/keyvault-secrets"; + +const credential = new DefaultAzureCredential(); +const client = new SecretClient( + "https://.vault.azure.net/", + credential +); + +// Get a secret +const secret = await client.getSecret("example-secret"); +console.log(`Secret value: ${secret.value}`); + +// Set a secret +await client.setSecret("new-secret", "secret-value"); + +// List secrets (metadata only, not values) +for await (const secretProperties of client.listPropertiesOfSecrets()) { + console.log(`Secret name: ${secretProperties.name}`); +} +``` + +## Common Pitfalls +- **Using access policies instead of RBAC**: Always set `enable_rbac_authorization = true`. Access policies are the legacy model and do not support fine-grained, identity-based control. +- **Deployer cannot write secrets**: When using RBAC mode, the Terraform/Bicep deploying principal needs the "Key Vault Secrets Officer" role to create secrets during deployment. Without this, `azapi_resource` secret resources will fail with 403. +- **Purge protection is irreversible**: Once `purge_protection_enabled = true` is set, it cannot be turned off. Deleted vaults/secrets remain for the full retention period. +- **Soft-deleted vault name collision**: A deleted vault still occupies its name for the retention period. Use `az keyvault list-deleted` to check for name conflicts. +- **Secret rotation not automatic**: Key Vault stores secrets but does not rotate them. Rotation requires Azure Function or Event Grid integration. +- **Network ACLs timing**: When setting `default_action = "Deny"`, ensure all required IPs and VNets are whitelisted first, or the deployer will lock itself out. + +## Production Backlog Items +- HSM-backed keys (Premium SKU) for regulatory compliance +- Network ACLs with default deny and explicit allow rules +- Diagnostic settings for audit logging (log all secret access) +- Key rotation policy with automated rotation via Event Grid +- Certificate management with auto-renewal +- Private endpoint with DNS integration +- Backup and disaster recovery procedures +- Integration with Azure Policy for compliance enforcement diff --git a/azext_prototype/knowledge/services/load-balancer.md b/azext_prototype/knowledge/services/load-balancer.md new file mode 100644 index 0000000..3dcaf8f --- /dev/null +++ b/azext_prototype/knowledge/services/load-balancer.md @@ -0,0 +1,374 @@ +--- +service_namespace: Microsoft.Network/loadBalancers +display_name: Azure Load Balancer +--- + +# Azure Load Balancer +> High-performance, ultra-low-latency Layer 4 (TCP/UDP) load balancer for distributing traffic across virtual machines, VM scale sets, and availability sets within a region. + +## When to Use + +- **TCP/UDP load balancing** -- distribute non-HTTP traffic (databases, custom TCP services, gaming servers) +- **VM-based architectures** -- load balance across VMs or VM scale sets +- **Internal service tiers** -- internal load balancer for private backend communication between tiers +- **High-throughput, low-latency** -- millions of flows per second with minimal latency overhead +- **HA ports** -- load balance all ports/protocols simultaneously for network virtual appliances +- NOT suitable for: HTTP/HTTPS routing (use Application Gateway), global distribution (use Front Door or Traffic Manager), or PaaS services (Container Apps, App Service have built-in LB) + +Choose Load Balancer for L4 traffic. Choose Application Gateway for L7 HTTP routing with SSL termination. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Basic is deprecated for new deployments | +| Type | Public or Internal | Internal for private backend tiers | +| Frontend IP | Static | Dynamic not supported on Standard SKU | +| Health probe | TCP or HTTP | HTTP preferred for application-level health | +| Session persistence | None | Client IP-based if sticky sessions needed | +| Outbound rules | Configured | Required for Standard LB outbound connectivity | + +## Terraform Patterns + +### Basic Resource (Public) + +```hcl +resource "azapi_resource" "lb_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "load_balancer" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + frontendIPConfigurations = [ + { + name = "lb-frontend" + properties = { + publicIPAddress = { + id = azapi_resource.lb_pip.id + } + } + } + ] + backendAddressPools = [ + { + name = "lb-backend-pool" + } + ] + loadBalancingRules = [ + { + name = "lb-rule-http" + properties = { + frontendIPConfiguration = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/frontendIPConfigurations/lb-frontend" + } + backendAddressPool = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/backendAddressPools/lb-backend-pool" + } + probe = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/probes/health-probe" + } + protocol = "Tcp" + frontendPort = 80 + backendPort = 80 + enableFloatingIP = false + idleTimeoutInMinutes = 4 + loadDistribution = "Default" + disableOutboundSnat = true # Use explicit outbound rules + } + } + ] + probes = [ + { + name = "health-probe" + properties = { + protocol = "Http" + port = 80 + requestPath = "/health" + intervalInSeconds = 15 + numberOfProbes = 2 + probeThreshold = 1 + } + } + ] + outboundRules = [ + { + name = "outbound-rule" + properties = { + frontendIPConfigurations = [ + { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/frontendIPConfigurations/lb-frontend" + } + ] + backendAddressPool = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/backendAddressPools/lb-backend-pool" + } + protocol = "All" + idleTimeoutInMinutes = 4 + allocatedOutboundPorts = 1024 + } + } + ] + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### Internal Load Balancer + +```hcl +resource "azapi_resource" "internal_lb" { + type = "Microsoft.Network/loadBalancers@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + frontendIPConfigurations = [ + { + name = "lb-frontend-internal" + properties = { + subnet = { + id = var.subnet_id + } + privateIPAllocationMethod = "Static" + privateIPAddress = var.private_ip # e.g., "10.0.1.10" + } + } + ] + backendAddressPools = [ + { + name = "lb-backend-pool" + } + ] + loadBalancingRules = [ + { + name = "lb-rule-tcp" + properties = { + frontendIPConfiguration = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/frontendIPConfigurations/lb-frontend-internal" + } + backendAddressPool = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/backendAddressPools/lb-backend-pool" + } + probe = { + id = "${var.resource_group_id}/providers/Microsoft.Network/loadBalancers/${var.name}/probes/health-probe" + } + protocol = "Tcp" + frontendPort = var.frontend_port + backendPort = var.backend_port + enableFloatingIP = false + idleTimeoutInMinutes = 4 + loadDistribution = "Default" + } + } + ] + probes = [ + { + name = "health-probe" + properties = { + protocol = "Tcp" + port = var.backend_port + intervalInSeconds = 15 + numberOfProbes = 2 + probeThreshold = 1 + } + } + ] + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor for load balancer management +resource "azapi_resource" "lb_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.load_balancer.id}-${var.admin_principal_id}-network-contributor") + parent_id = azapi_resource.load_balancer.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Azure Load Balancer does not use private endpoints. Internal Load Balancer is inherently private -- it is placed in a VNet subnet with a private frontend IP. + +## Bicep Patterns + +### Basic Resource (Public) + +```bicep +@description('Name of the Load Balancer') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource lbPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource loadBalancer 'Microsoft.Network/loadBalancers@2024-01-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard' + } + properties: { + frontendIPConfigurations: [ + { + name: 'lb-frontend' + properties: { + publicIPAddress: { + id: lbPip.id + } + } + } + ] + backendAddressPools: [ + { + name: 'lb-backend-pool' + } + ] + loadBalancingRules: [ + { + name: 'lb-rule-http' + properties: { + frontendIPConfiguration: { + id: resourceId('Microsoft.Network/loadBalancers/frontendIPConfigurations', name, 'lb-frontend') + } + backendAddressPool: { + id: resourceId('Microsoft.Network/loadBalancers/backendAddressPools', name, 'lb-backend-pool') + } + probe: { + id: resourceId('Microsoft.Network/loadBalancers/probes', name, 'health-probe') + } + protocol: 'Tcp' + frontendPort: 80 + backendPort: 80 + enableFloatingIP: false + idleTimeoutInMinutes: 4 + disableOutboundSnat: true + } + } + ] + probes: [ + { + name: 'health-probe' + properties: { + protocol: 'Http' + port: 80 + requestPath: '/health' + intervalInSeconds: 15 + numberOfProbes: 2 + probeThreshold: 1 + } + } + ] + outboundRules: [ + { + name: 'outbound-rule' + properties: { + frontendIPConfigurations: [ + { + id: resourceId('Microsoft.Network/loadBalancers/frontendIPConfigurations', name, 'lb-frontend') + } + ] + backendAddressPool: { + id: resourceId('Microsoft.Network/loadBalancers/backendAddressPools', name, 'lb-backend-pool') + } + protocol: 'All' + idleTimeoutInMinutes: 4 + allocatedOutboundPorts: 1024 + } + } + ] + } +} + +output id string = loadBalancer.id +output frontendIpId string = loadBalancer.properties.frontendIPConfigurations[0].id +output backendPoolId string = loadBalancer.properties.backendAddressPools[0].id +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Using Basic SKU | Basic is deprecated, no SLA, no availability zones | Always use Standard SKU for new deployments | +| No outbound rule on Standard LB | VMs behind Standard LB lose default outbound internet | Configure explicit outbound rule or use NAT Gateway | +| Health probe on wrong port/path | All backends marked unhealthy; traffic stops | Verify probe endpoint returns HTTP 200 and is reachable | +| Mixing Basic and Standard resources | Deployment fails; Basic and Standard cannot be mixed | Ensure all resources (LB, PIPs, VMs) are same SKU tier | +| Not disabling SNAT on LB rules | Port exhaustion when outbound rules also configured | Set `disableOutboundSnat = true` on LB rules when using outbound rules | +| Session persistence misconfiguration | Stateful apps fail with random distribution | Use `ClientIP` or `ClientIPProtocol` for sticky sessions | +| Idle timeout too short | Long-running connections dropped | Increase `idleTimeoutInMinutes` (max 30) or enable TCP keepalives | +| Forgetting backend pool association | VMs not receiving traffic | Associate VM NICs with the backend pool | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Availability zones | P1 | Deploy zone-redundant LB with zone-redundant frontend IP | +| Multiple frontend IPs | P3 | Add frontend IPs for different services or SNAT capacity | +| Cross-region LB | P2 | Deploy Global tier for cross-region failover (replaces Traffic Manager for L4) | +| Diagnostic logging | P2 | Enable load balancer metrics and health probe logs to Log Analytics | +| NAT Gateway for outbound | P2 | Replace outbound rules with NAT Gateway for predictable SNAT | +| HA Ports rule | P3 | Configure HA ports for NVA scenarios (all ports/protocols) | +| Connection draining | P2 | Configure idle timeout and TCP reset for graceful connection handling | +| Backend pool scaling | P3 | Integrate with VM scale sets for auto-scaling backend pools | +| Health probe refinement | P2 | Switch from TCP to HTTP probes with application-level health checks | +| Inbound NAT rules | P3 | Configure port-based NAT for direct VM access if needed | diff --git a/azext_prototype/knowledge/services/local-network-gateway.md b/azext_prototype/knowledge/services/local-network-gateway.md new file mode 100644 index 0000000..4c50d89 --- /dev/null +++ b/azext_prototype/knowledge/services/local-network-gateway.md @@ -0,0 +1,119 @@ +--- +service_namespace: Microsoft.Network/localNetworkGateways +display_name: Local Network Gateway +--- + +# Local Network Gateway + +> Representation of an on-premises VPN device in Azure, defining the public IP address and address ranges of the remote network for site-to-site VPN connectivity. + +## When to Use +- **Site-to-site VPN** -- every S2S VPN connection requires a local network gateway to represent the on-premises endpoint +- **Multiple on-premises sites** -- create one local network gateway per remote site/branch +- **BGP-enabled VPN** -- specify the on-premises BGP peer address and ASN +- Required companion to `Microsoft.Network/connections` of type `IPsec` + +A local network gateway is purely a metadata resource describing the remote network. It does not provision any infrastructure itself. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Gateway IP | On-premises public IP | Must be publicly routable | +| Address prefixes | On-premises CIDR(s) | e.g., 10.1.0.0/16, 192.168.0.0/24 | +| BGP | Disabled | Enable for dynamic routing in production | +| FQDN | Not used | Alternative to IP for dynamic-IP devices | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "local_gw" { + type = "Microsoft.Network/localNetworkGateways@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + gatewayIpAddress = var.on_premises_public_ip # e.g., "203.0.113.1" + localNetworkAddressSpace = { + addressPrefixes = var.on_premises_address_prefixes # e.g., ["10.1.0.0/16"] + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor on the resource group covers local network gateway management. +# Role ID: 4d97b98b-1d4f-4787-a291-c67834d212e7 +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the local network gateway') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Public IP of the on-premises VPN device') +param gatewayIpAddress string + +@description('On-premises address prefixes') +param addressPrefixes array + +param tags object = {} + +resource localGw 'Microsoft.Network/localNetworkGateways@2024-01-01' = { + name: name + location: location + tags: tags + properties: { + gatewayIpAddress: gatewayIpAddress + localNetworkAddressSpace: { + addressPrefixes: addressPrefixes + } + } +} + +output id string = localGw.id +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Local network gateways define network routing metadata; applications are unaware of their existence. + +### C# +Infrastructure -- transparent to application code. Local network gateways define network routing metadata; applications are unaware of their existence. + +### Node.js +Infrastructure -- transparent to application code. Local network gateways define network routing metadata; applications are unaware of their existence. + +## Common Pitfalls + +1. **Address prefix overlap with Azure VNet** -- On-premises address prefixes must not overlap with any Azure VNet address space. Overlapping ranges cause asymmetric routing and connection failures. +2. **Gateway IP must be publicly routable** -- Private IPs (10.x, 172.16.x, 192.168.x) are not valid for `gatewayIpAddress`. If the on-premises device is behind NAT, use the NAT public IP. +3. **Updating address prefixes disconnects the tunnel** -- Changing `localNetworkAddressSpace` briefly disrupts the VPN connection while routes reconverge. Plan maintenance windows. +4. **BGP peer address not in address space** -- When using BGP, the `bgpPeeringAddress` must be routable from Azure but should not be in the `localNetworkAddressSpace` prefixes (it is learned via BGP, not static routes). +5. **FQDN vs IP mutual exclusivity** -- You can set either `gatewayIpAddress` or `fqdn`, not both. FQDN is useful when the on-premises public IP is dynamic (resolved via DNS). +6. **Deleting while connection exists** -- A local network gateway cannot be deleted while a connection references it. Delete the connection first. + +## Production Backlog Items + +- [ ] Enable BGP with on-premises ASN and peering address for dynamic routing +- [ ] Configure FQDN instead of static IP if on-premises public IP is dynamic +- [ ] Document all on-premises address prefixes and keep them synchronized +- [ ] Plan for multiple local network gateways if connecting to multiple branch offices +- [ ] Implement monitoring for gateway IP reachability +- [ ] Add secondary local network gateway for redundant on-premises VPN device diff --git a/azext_prototype/knowledge/services/log-analytics-private-link-scope.md b/azext_prototype/knowledge/services/log-analytics-private-link-scope.md new file mode 100644 index 0000000..d9572f6 --- /dev/null +++ b/azext_prototype/knowledge/services/log-analytics-private-link-scope.md @@ -0,0 +1,136 @@ +--- +service_namespace: Microsoft.Insights/privateLinkScopes +display_name: Azure Monitor Private Link Scope +--- + +# Azure Monitor Private Link Scope (AMPLS) + +> Network isolation boundary that groups Azure Monitor resources (Log Analytics workspaces, Application Insights) behind a single private endpoint, controlling data ingestion and query access over private network. + +## When to Use +- **Private network monitoring** -- send telemetry from VNet-connected VMs to Log Analytics/App Insights over private endpoints instead of public internet +- **Compliance requirements** -- data must not traverse public networks (PCI-DSS, HIPAA) +- **Centralized private link management** -- one AMPLS with one private endpoint covers multiple monitoring resources +- Required when Log Analytics workspaces or App Insights resources have public network access disabled + +An AMPLS acts as a grouping mechanism. You create one AMPLS, add scoped resources (workspaces, App Insights), then create a private endpoint to the AMPLS. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Ingestion access mode | Open | Allows mixed public/private ingestion for POC | +| Query access mode | Open | Allows mixed public/private queries for POC | +| Scoped resources | 1-2 workspaces | Add as needed | + +**Important:** Using `PrivateOnly` access mode blocks ALL public access to scoped resources, including Azure portal queries. Use `Open` for POC. + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "ampls" { + type = "Microsoft.Insights/privateLinkScopes@2021-07-01-preview" + name = var.name + location = "global" # AMPLS is a global resource + parent_id = var.resource_group_id + + body = { + properties = { + accessModeSettings = { + ingestionAccessMode = "Open" # "PrivateOnly" for production + queryAccessMode = "Open" # "PrivateOnly" for production + } + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### RBAC Assignment + +```hcl +# Monitoring Contributor for managing the AMPLS +resource "azapi_resource" "monitoring_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.ampls.id}-${var.principal_id}-monitoring-contributor") + parent_id = azapi_resource.ampls.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/749f88d5-cbae-40b8-bcfc-e573ddc772fa" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Private Link Scope') +param name string + +@description('Ingestion access mode') +@allowed(['Open', 'PrivateOnly']) +param ingestionAccessMode string = 'Open' + +@description('Query access mode') +@allowed(['Open', 'PrivateOnly']) +param queryAccessMode string = 'Open' + +param tags object = {} + +resource ampls 'Microsoft.Insights/privateLinkScopes@2021-07-01-preview' = { + name: name + location: 'global' + tags: tags + properties: { + accessModeSettings: { + ingestionAccessMode: ingestionAccessMode + queryAccessMode: queryAccessMode + } + } +} + +output id string = ampls.id +output name string = ampls.name +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. AMPLS controls network routing for monitoring data; applications send telemetry using the same SDKs and endpoints regardless of AMPLS configuration. + +### C# +Infrastructure -- transparent to application code. AMPLS controls network routing for monitoring data; applications send telemetry using the same SDKs and endpoints regardless of AMPLS configuration. + +### Node.js +Infrastructure -- transparent to application code. AMPLS controls network routing for monitoring data; applications send telemetry using the same SDKs and endpoints regardless of AMPLS configuration. + +## Common Pitfalls + +1. **Location must be `"global"`** -- AMPLS is a global resource. Specifying a region causes deployment failure. +2. **PrivateOnly locks out portal access** -- Setting `queryAccessMode` to `PrivateOnly` blocks Azure portal log queries unless the portal is accessed from a VNet-connected machine. +3. **One AMPLS per VNet** -- A VNet should connect to at most one AMPLS via private endpoint. Multiple AMPLS connections from the same VNet cause DNS conflicts. +4. **Scoped resource limits** -- An AMPLS supports up to 50 scoped resources. Plan capacity for large environments. +5. **DNS configuration is complex** -- AMPLS private endpoints require DNS records for multiple Azure Monitor sub-domains (`ods.opinsights.azure.com`, `oms.opinsights.azure.com`, `agentsvc.azure-automation.net`, etc.). +6. **Access mode applies to ALL scoped resources** -- Setting `PrivateOnly` affects every workspace/App Insights in the scope. You cannot mix public and private per resource within one AMPLS. +7. **Existing data collection may break** -- Switching from `Open` to `PrivateOnly` immediately blocks public ingestion. Ensure all agents are configured for private endpoints first. + +## Production Backlog Items + +- [ ] Switch access modes to `PrivateOnly` for both ingestion and queries +- [ ] Create private endpoint in the monitoring VNet connected to the AMPLS +- [ ] Configure DNS (private DNS zones) for all Azure Monitor sub-domains +- [ ] Add all Log Analytics workspaces and App Insights resources as scoped resources +- [ ] Verify agent connectivity over private link +- [ ] Test Azure portal query access via VPN/ExpressRoute +- [ ] Document network architecture for monitoring data flow diff --git a/azext_prototype/knowledge/services/log-analytics-private-link-scoped-resource.md b/azext_prototype/knowledge/services/log-analytics-private-link-scoped-resource.md new file mode 100644 index 0000000..d51d29f --- /dev/null +++ b/azext_prototype/knowledge/services/log-analytics-private-link-scoped-resource.md @@ -0,0 +1,115 @@ +--- +service_namespace: Microsoft.Insights/privateLinkScopes/scopedResources +display_name: AMPLS Scoped Resource +depends_on: + - Microsoft.Insights/privateLinkScopes +--- + +# AMPLS Scoped Resource + +> Association between an Azure Monitor Private Link Scope (AMPLS) and a specific monitoring resource (Log Analytics workspace or Application Insights), enabling that resource to be accessed through the AMPLS private endpoint. + +## When to Use +- **Add workspace to private link** -- include a Log Analytics workspace in the AMPLS for private ingestion and query +- **Add App Insights to private link** -- include an Application Insights resource for private telemetry collection +- Every monitoring resource that should be accessible over the private endpoint must be added as a scoped resource + +Each scoped resource creates a link between the AMPLS and the target monitoring resource. Without this link, the monitoring resource is not reachable via the AMPLS private endpoint. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Linked resource | Log Analytics workspace ID | Or Application Insights resource ID | +| Name | Descriptive (e.g., `workspace-link`) | Must be unique within the AMPLS | + +## Terraform Patterns + +### Basic Resource + +```hcl +# Link a Log Analytics workspace to the AMPLS +resource "azapi_resource" "scoped_workspace" { + type = "Microsoft.Insights/privateLinkScopes/scopedResources@2021-07-01-preview" + name = "workspace-${var.workspace_name}" + parent_id = azapi_resource.ampls.id + + body = { + properties = { + linkedResourceId = var.workspace_id + } + } +} + +# Link an Application Insights resource to the AMPLS +resource "azapi_resource" "scoped_appinsights" { + type = "Microsoft.Insights/privateLinkScopes/scopedResources@2021-07-01-preview" + name = "appinsights-${var.appinsights_name}" + parent_id = azapi_resource.ampls.id + + body = { + properties = { + linkedResourceId = var.appinsights_id + } + } +} +``` + +### RBAC Assignment + +```hcl +# Scoped resource management inherits from the parent AMPLS RBAC. +# Monitoring Contributor (749f88d5-cbae-40b8-bcfc-e573ddc772fa) on the AMPLS is sufficient. +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name for the scoped resource link') +param scopedResourceName string + +@description('Resource ID of the Log Analytics workspace or App Insights') +param linkedResourceId string + +resource scopedResource 'Microsoft.Insights/privateLinkScopes/scopedResources@2021-07-01-preview' = { + parent: ampls + name: scopedResourceName + properties: { + linkedResourceId: linkedResourceId + } +} + +output id string = scopedResource.id +output provisioningState string = scopedResource.properties.provisioningState +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Scoped resources define which monitoring resources are accessible over private link; applications are unaware of this configuration. + +### C# +Infrastructure -- transparent to application code. Scoped resources define which monitoring resources are accessible over private link; applications are unaware of this configuration. + +### Node.js +Infrastructure -- transparent to application code. Scoped resources define which monitoring resources are accessible over private link; applications are unaware of this configuration. + +## Common Pitfalls + +1. **50 resource limit per AMPLS** -- Each AMPLS supports a maximum of 50 scoped resources. Plan for this limit in large environments. +2. **Resource can be in only 5 AMPLS** -- A single workspace or App Insights resource can be linked to at most 5 AMPLS. Exceeding this causes deployment failure. +3. **Linked resource must exist** -- The `linkedResourceId` must point to an existing Log Analytics workspace or Application Insights resource. Deploying with a non-existent ID fails. +4. **Removing breaks private access** -- Deleting a scoped resource immediately removes private endpoint access to that monitoring resource. If `PrivateOnly` mode is active, all data ingestion and queries stop. +5. **Name must be unique within AMPLS** -- Two scoped resources in the same AMPLS cannot share a name. Use a naming convention that includes the target resource name. +6. **Cross-subscription links** -- Scoped resources can link to monitoring resources in different subscriptions, but the deploying identity needs Reader access on the target resource. + +## Production Backlog Items + +- [ ] Inventory all Log Analytics workspaces and App Insights resources that need private access +- [ ] Add all required monitoring resources as scoped resources +- [ ] Verify private endpoint DNS resolution for each scoped resource +- [ ] Monitor provisioning state for successful linkage +- [ ] Plan for the 50-resource limit if the environment is large +- [ ] Document which resources are scoped per AMPLS for the networking team diff --git a/azext_prototype/knowledge/services/log-analytics.md b/azext_prototype/knowledge/services/log-analytics.md index 87d97ba..1148c01 100644 --- a/azext_prototype/knowledge/services/log-analytics.md +++ b/azext_prototype/knowledge/services/log-analytics.md @@ -1,337 +1,419 @@ -# Log Analytics Workspace -> Centralized log aggregation and query service in Azure Monitor, providing the data store and query engine for diagnostics, metrics, and operational insights across all Azure resources. - -## When to Use - -- Foundation service for all Azure monitoring and observability -- Collecting diagnostic logs and metrics from Azure resources -- Backing store for Application Insights (workspace-based) -- Required by Container Apps Environment -- Centralized log querying with Kusto Query Language (KQL) -- Security monitoring with Microsoft Sentinel -- NOT suitable for: real-time streaming analytics (use Event Hubs + Stream Analytics), long-term archival storage (use Storage Account export), or application-level custom metrics without diagnostic settings - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | PerGB2018 | Only pricing tier for new workspaces | -| Retention | 30 days | Free retention period; beyond 30 days incurs charges | -| Daily cap | Not set (unlimited) | Set a cap in production to control costs | -| Location | Same as resource group | Must match or be in a supported region | - -**Foundation service**: Log Analytics Workspace is typically created in Stage 1 (foundation) and referenced by all subsequent resources that need monitoring. Create it early in the deployment sequence. - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_log_analytics_workspace" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - sku = "PerGB2018" - retention_in_days = var.retention_in_days # 30 for POC - - tags = var.tags -} -``` - -### With Diagnostic Settings (apply to other resources) - -```hcl -# Example: send Key Vault diagnostics to Log Analytics -resource "azurerm_monitor_diagnostic_setting" "keyvault" { - name = "diag-${var.keyvault_name}" - target_resource_id = var.keyvault_id - log_analytics_workspace_id = azurerm_log_analytics_workspace.this.id - - enabled_log { - category = "AuditEvent" - } - - enabled_log { - category = "AzurePolicyEvaluationDetails" - } - - metric { - category = "AllMetrics" - } -} - -# Example: send App Service diagnostics to Log Analytics -resource "azurerm_monitor_diagnostic_setting" "webapp" { - name = "diag-${var.webapp_name}" - target_resource_id = var.webapp_id - log_analytics_workspace_id = azurerm_log_analytics_workspace.this.id - - enabled_log { - category = "AppServiceHTTPLogs" - } - - enabled_log { - category = "AppServiceConsoleLogs" - } - - enabled_log { - category = "AppServiceAppLogs" - } - - metric { - category = "AllMetrics" - } -} -``` - -### RBAC Assignment - -```hcl -# Grant read access for querying logs -resource "azurerm_role_assignment" "reader" { - scope = azurerm_log_analytics_workspace.this.id - role_definition_name = "Log Analytics Reader" - principal_id = var.reader_principal_id -} - -# Grant contributor access for managing workspace settings -resource "azurerm_role_assignment" "contributor" { - scope = azurerm_log_analytics_workspace.this.id - role_definition_name = "Log Analytics Contributor" - principal_id = var.admin_principal_id -} -``` - -### Private Endpoint - -```hcl -# Private endpoint for Log Analytics is via Azure Monitor Private Link Scope (AMPLS) -# This is NOT typically needed for POC -- public ingestion and query endpoints are fine -# Include as a production backlog item - -# For production: -resource "azurerm_monitor_private_link_scope" "this" { - count = var.enable_private_link ? 1 : 0 - name = "ampls-${var.name}" - resource_group_name = var.resource_group_name - - tags = var.tags -} - -resource "azurerm_monitor_private_link_scoped_service" "this" { - count = var.enable_private_link ? 1 : 0 - name = "amplsservice-${var.name}" - resource_group_name = var.resource_group_name - scope_name = azurerm_monitor_private_link_scope.this[0].name - linked_resource_id = azurerm_log_analytics_workspace.this.id -} - -resource "azurerm_private_endpoint" "this" { - count = var.enable_private_link && var.subnet_id != null ? 1 : 0 - - name = "pe-${var.name}" - location = var.location - resource_group_name = var.resource_group_name - subnet_id = var.subnet_id - - private_service_connection { - name = "psc-${var.name}" - private_connection_resource_id = azurerm_monitor_private_link_scope.this[0].id - subresource_names = ["azuremonitor"] - is_manual_connection = false - } - - tags = var.tags -} -``` - -## Bicep Patterns - -### Basic Resource - -```bicep -param name string -param location string -param retentionInDays int = 30 -param tags object = {} - -resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = { - name: name - location: location - properties: { - sku: { - name: 'PerGB2018' - } - retentionInDays: retentionInDays - } - tags: tags -} - -output id string = logAnalytics.id -output name string = logAnalytics.name -output customerId string = logAnalytics.properties.customerId -``` - -### Diagnostic Settings (applied to another resource) - -```bicep -param workspaceId string -param targetResourceId string -param settingName string - -resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { - name: settingName - scope: targetResource - properties: { - workspaceId: workspaceId - logs: [ - { - category: 'AuditEvent' - enabled: true - } - ] - metrics: [ - { - category: 'AllMetrics' - enabled: true - } - ] - } -} -``` - -### RBAC Assignment - -```bicep -param principalId string - -resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' existing = { - name: logAnalyticsName -} - -// Log Analytics Reader -resource readerRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { - name: guid(logAnalytics.id, principalId, '73c42c96-874c-492b-b04d-ab87d138a893') - scope: logAnalytics - properties: { - roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '73c42c96-874c-492b-b04d-ab87d138a893') - principalId: principalId - principalType: 'ServicePrincipal' - } -} -``` - -## Application Code - -Log Analytics Workspace is primarily an infrastructure service. Application code interacts with it indirectly through SDKs that emit telemetry (App Insights, OpenTelemetry) or directly for log queries. - -### Python (Query Logs) - -```python -import os -from azure.identity import DefaultAzureCredential, ManagedIdentityCredential -from azure.monitor.query import LogsQueryClient -from datetime import timedelta - -def get_credential(): - client_id = os.getenv("AZURE_CLIENT_ID") - if client_id: - return ManagedIdentityCredential(client_id=client_id) - return DefaultAzureCredential() - -workspace_id = os.getenv("LOG_ANALYTICS_WORKSPACE_ID") # Customer ID (GUID) -credential = get_credential() - -client = LogsQueryClient(credential) -response = client.query_workspace( - workspace_id=workspace_id, - query="AppRequests | summarize count() by resultCode | order by count_ desc", - timespan=timedelta(hours=24), -) - -for row in response.tables[0].rows: - print(f"Status {row[0]}: {row[1]} requests") -``` - -### C# (Query Logs) - -```csharp -using Azure.Identity; -using Azure.Monitor.Query; -using Azure.Monitor.Query.Models; - -var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); -var credential = string.IsNullOrEmpty(clientId) - ? new DefaultAzureCredential() - : new ManagedIdentityCredential(clientId); - -var workspaceId = Environment.GetEnvironmentVariable("LOG_ANALYTICS_WORKSPACE_ID"); -var client = new LogsQueryClient(credential); - -var response = await client.QueryWorkspaceAsync( - workspaceId, - "AppRequests | summarize count() by resultCode | order by count_ desc", - new QueryTimeRange(TimeSpan.FromHours(24)) -); - -foreach (var row in response.Value.Table.Rows) -{ - Console.WriteLine($"Status {row[0]}: {row[1]} requests"); -} -``` - -### Node.js (Query Logs) - -```javascript -const { LogsQueryClient } = require("@azure/monitor-query"); -const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); - -function getCredential() { - const clientId = process.env.AZURE_CLIENT_ID; - return clientId - ? new ManagedIdentityCredential(clientId) - : new DefaultAzureCredential(); -} - -const workspaceId = process.env.LOG_ANALYTICS_WORKSPACE_ID; -const client = new LogsQueryClient(getCredential()); - -async function queryLogs() { - const result = await client.queryWorkspace( - workspaceId, - "AppRequests | summarize count() by resultCode | order by count_ desc", - { duration: "PT24H" } - ); - - for (const row of result.tables[0].rows) { - console.log(`Status ${row[0]}: ${row[1]} requests`); - } -} -``` - -## Common Pitfalls - -| Pitfall | Impact | Prevention | -|---------|--------|-----------| -| Creating multiple workspaces unnecessarily | Fragmented logs, harder to query across resources | Use a single workspace per environment for most POCs | -| Not setting retention policy | Default 30 days may be too short for production | Configure retention explicitly; accept 30 days for POC | -| Ignoring ingestion costs | Unexpected bills from high-volume log sources | Set daily cap for production; monitor ingestion volume | -| Not enabling diagnostic settings on resources | Resources create no logs in the workspace | Add `azurerm_monitor_diagnostic_setting` for each resource | -| Workspace region mismatch | Some diagnostic settings require same-region workspace | Deploy workspace in the same region as the resource group | -| Querying without proper RBAC | Access denied on workspace queries | Assign `Log Analytics Reader` role for query access | -| Confusing workspace ID with resource ID | API calls fail | Workspace ID (customerId) is the GUID used for queries; resource ID is the ARM path | - -## Production Backlog Items - -| Item | Priority | Description | -|------|----------|-------------| -| Data retention policies | P3 | Configure per-table retention beyond the default 30 days for compliance | -| Daily ingestion cap | P3 | Set daily cap to prevent unexpected cost spikes | -| Workspace-based access control | P3 | Configure table-level RBAC for fine-grained access to sensitive logs | -| Azure Private Link Scope | P1 | Deploy AMPLS for private ingestion and query endpoints | -| Data export rules | P4 | Configure continuous export to Storage Account for long-term archival | -| Dedicated cluster | P4 | For high-volume scenarios (500+ GB/day), use a dedicated cluster for cost optimization | -| Alert rules | P3 | Create log-based and metric-based alert rules for operational monitoring | -| Workbooks and dashboards | P3 | Build Azure Monitor Workbooks for visual dashboards | -| Cross-workspace queries | P4 | Configure cross-workspace queries if multiple workspaces exist | -| Sentinel integration | P2 | Enable Microsoft Sentinel on the workspace for security monitoring | +--- +service_namespace: Microsoft.OperationalInsights/workspaces +display_name: Log Analytics Workspace +--- + +# Log Analytics Workspace +> Centralized log aggregation and query service in Azure Monitor, providing the data store and query engine for diagnostics, metrics, and operational insights across all Azure resources. + +## When to Use + +- Foundation service for all Azure monitoring and observability +- Collecting diagnostic logs and metrics from Azure resources +- Backing store for Application Insights (workspace-based) +- Required by Container Apps Environment +- Centralized log querying with Kusto Query Language (KQL) +- Security monitoring with Microsoft Sentinel +- NOT suitable for: real-time streaming analytics (use Event Hubs + Stream Analytics), long-term archival storage (use Storage Account export), or application-level custom metrics without diagnostic settings + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | PerGB2018 | Only pricing tier for new workspaces | +| Retention | 30 days | Free retention period; beyond 30 days incurs charges | +| Daily cap | Not set (unlimited) | Set a cap in production to control costs | +| Location | Same as resource group | Must match or be in a supported region | + +**Foundation service**: Log Analytics Workspace is typically created in Stage 1 (foundation) and referenced by all subsequent resources that need monitoring. Create it early in the deployment sequence. + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "log_analytics" { + type = "Microsoft.OperationalInsights/workspaces@2023-09-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + sku = { + name = "PerGB2018" + } + retentionInDays = var.retention_in_days # 30 for POC + } + } + + tags = var.tags + + response_export_values = ["properties.customerId"] +} +``` + +### With Diagnostic Settings (apply to other resources) + +```hcl +# Example: send Key Vault diagnostics to Log Analytics +resource "azapi_resource" "diag_keyvault" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.keyvault_name}" + parent_id = var.keyvault_id + + body = { + properties = { + workspaceId = azapi_resource.log_analytics.id + logs = [ + { + category = "AuditEvent" + enabled = true + }, + { + category = "AzurePolicyEvaluationDetails" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } +} + +# Example: send App Service diagnostics to Log Analytics +resource "azapi_resource" "diag_webapp" { + type = "Microsoft.Insights/diagnosticSettings@2021-05-01-preview" + name = "diag-${var.webapp_name}" + parent_id = var.webapp_id + + body = { + properties = { + workspaceId = azapi_resource.log_analytics.id + logs = [ + { + category = "AppServiceHTTPLogs" + enabled = true + }, + { + category = "AppServiceConsoleLogs" + enabled = true + }, + { + category = "AppServiceAppLogs" + enabled = true + } + ] + metrics = [ + { + category = "AllMetrics" + enabled = true + } + ] + } + } +} +``` + +### RBAC Assignment + +```hcl +# Grant read access for querying logs +resource "azapi_resource" "reader_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.log_analytics.id}${var.reader_principal_id}reader") + parent_id = azapi_resource.log_analytics.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/73c42c96-874c-492b-b04d-ab87d138a893" # Log Analytics Reader + principalId = var.reader_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant contributor access for managing workspace settings +resource "azapi_resource" "contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.log_analytics.id}${var.admin_principal_id}contributor") + parent_id = azapi_resource.log_analytics.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/92aaf0da-9dab-42b6-94a3-d43ce8d16293" # Log Analytics Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +# Private endpoint for Log Analytics is via Azure Monitor Private Link Scope (AMPLS) +# Unless told otherwise, private endpoint via AMPLS is required per governance policy -- +# publicNetworkAccessForIngestion and publicNetworkAccessForQuery should be set to "Disabled" + +# For production: +resource "azapi_resource" "ampls" { + count = var.enable_private_link ? 1 : 0 + type = "Microsoft.Insights/privateLinkScopes@2021-07-01-preview" + name = "ampls-${var.name}" + location = "global" + parent_id = var.resource_group_id + + body = { + properties = { + accessModeSettings = { + ingestionAccessMode = "PrivateOnly" + queryAccessMode = "PrivateOnly" + } + } + } + + tags = var.tags +} + +resource "azapi_resource" "ampls_scoped_service" { + count = var.enable_private_link ? 1 : 0 + type = "Microsoft.Insights/privateLinkScopes/scopedResources@2021-07-01-preview" + name = "amplsservice-${var.name}" + parent_id = azapi_resource.ampls[0].id + + body = { + properties = { + linkedResourceId = azapi_resource.log_analytics.id + } + } +} + +resource "azapi_resource" "private_endpoint" { + count = var.enable_private_link && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.ampls[0].id + groupIds = ["azuremonitor"] + } + } + ] + } + } + + tags = var.tags +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param retentionInDays int = 30 +param tags object = {} + +resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = { + name: name + location: location + properties: { + sku: { + name: 'PerGB2018' + } + retentionInDays: retentionInDays + } + tags: tags +} + +output id string = logAnalytics.id +output name string = logAnalytics.name +output customerId string = logAnalytics.properties.customerId +``` + +### Diagnostic Settings (applied to another resource) + +```bicep +param workspaceId string +param targetResourceId string +param settingName string + +resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { + name: settingName + scope: targetResource + properties: { + workspaceId: workspaceId + logs: [ + { + category: 'AuditEvent' + enabled: true + } + ] + metrics: [ + { + category: 'AllMetrics' + enabled: true + } + ] + } +} +``` + +### RBAC Assignment + +```bicep +param principalId string + +resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' existing = { + name: logAnalyticsName +} + +// Log Analytics Reader +resource readerRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(logAnalytics.id, principalId, '73c42c96-874c-492b-b04d-ab87d138a893') + scope: logAnalytics + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '73c42c96-874c-492b-b04d-ab87d138a893') + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Application Code + +Log Analytics Workspace is primarily an infrastructure service. Application code interacts with it indirectly through SDKs that emit telemetry (App Insights, OpenTelemetry) or directly for log queries. + +### Python (Query Logs) + +```python +import os +from azure.identity import DefaultAzureCredential, ManagedIdentityCredential +from azure.monitor.query import LogsQueryClient +from datetime import timedelta + +def get_credential(): + client_id = os.getenv("AZURE_CLIENT_ID") + if client_id: + return ManagedIdentityCredential(client_id=client_id) + return DefaultAzureCredential() + +workspace_id = os.getenv("LOG_ANALYTICS_WORKSPACE_ID") # Customer ID (GUID) +credential = get_credential() + +client = LogsQueryClient(credential) +response = client.query_workspace( + workspace_id=workspace_id, + query="AppRequests | summarize count() by resultCode | order by count_ desc", + timespan=timedelta(hours=24), +) + +for row in response.tables[0].rows: + print(f"Status {row[0]}: {row[1]} requests") +``` + +### C# (Query Logs) + +```csharp +using Azure.Identity; +using Azure.Monitor.Query; +using Azure.Monitor.Query.Models; + +var clientId = Environment.GetEnvironmentVariable("AZURE_CLIENT_ID"); +var credential = string.IsNullOrEmpty(clientId) + ? new DefaultAzureCredential() + : new ManagedIdentityCredential(clientId); + +var workspaceId = Environment.GetEnvironmentVariable("LOG_ANALYTICS_WORKSPACE_ID"); +var client = new LogsQueryClient(credential); + +var response = await client.QueryWorkspaceAsync( + workspaceId, + "AppRequests | summarize count() by resultCode | order by count_ desc", + new QueryTimeRange(TimeSpan.FromHours(24)) +); + +foreach (var row in response.Value.Table.Rows) +{ + Console.WriteLine($"Status {row[0]}: {row[1]} requests"); +} +``` + +### Node.js (Query Logs) + +```javascript +const { LogsQueryClient } = require("@azure/monitor-query"); +const { DefaultAzureCredential, ManagedIdentityCredential } = require("@azure/identity"); + +function getCredential() { + const clientId = process.env.AZURE_CLIENT_ID; + return clientId + ? new ManagedIdentityCredential(clientId) + : new DefaultAzureCredential(); +} + +const workspaceId = process.env.LOG_ANALYTICS_WORKSPACE_ID; +const client = new LogsQueryClient(getCredential()); + +async function queryLogs() { + const result = await client.queryWorkspace( + workspaceId, + "AppRequests | summarize count() by resultCode | order by count_ desc", + { duration: "PT24H" } + ); + + for (const row of result.tables[0].rows) { + console.log(`Status ${row[0]}: ${row[1]} requests`); + } +} +``` + +## CRITICAL: ARM Property Placement +- `disableLocalAuth` is a **top-level** property under `properties`, **NOT** inside `properties.features` +- The ARM API _silently drops_ `disableLocalAuth` if nested inside `features` +- CORRECT: `properties = { disableLocalAuth = false, features = { enableLogAccessUsingOnlyResourcePermissions = true } }` +- WRONG: `properties = { features = { disableLocalAuth = false } }` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Creating multiple workspaces unnecessarily | Fragmented logs, harder to query across resources | Use a single workspace per environment for most POCs | +| Not setting retention policy | Default 30 days may be too short for production | Configure retention explicitly; accept 30 days for POC | +| Ignoring ingestion costs | Unexpected bills from high-volume log sources | Set daily cap for production; monitor ingestion volume | +| Not enabling diagnostic settings on resources | Resources create no logs in the workspace | Add an `azapi_resource` of type `Microsoft.Insights/diagnosticSettings` for each resource | +| Workspace region mismatch | Some diagnostic settings require same-region workspace | Deploy workspace in the same region as the resource group | +| Querying without proper RBAC | Access denied on workspace queries | Assign `Log Analytics Reader` role for query access | +| Confusing workspace ID with resource ID | API calls fail | Workspace ID (customerId) is the GUID used for queries; resource ID is the ARM path | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Data retention policies | P3 | Configure per-table retention beyond the default 30 days for compliance | +| Daily ingestion cap | P3 | Set daily cap to prevent unexpected cost spikes | +| Workspace-based access control | P3 | Configure table-level RBAC for fine-grained access to sensitive logs | +| Azure Private Link Scope | P1 | Deploy AMPLS for private ingestion and query endpoints | +| Data export rules | P4 | Configure continuous export to Storage Account for long-term archival | +| Dedicated cluster | P4 | For high-volume scenarios (500+ GB/day), use a dedicated cluster for cost optimization | +| Alert rules | P3 | Create log-based and metric-based alert rules for operational monitoring | +| Workbooks and dashboards | P3 | Build Azure Monitor Workbooks for visual dashboards | +| Cross-workspace queries | P4 | Configure cross-workspace queries if multiple workspaces exist | +| Sentinel integration | P2 | Enable Microsoft Sentinel on the workspace for security monitoring | diff --git a/azext_prototype/knowledge/services/logic-apps.md b/azext_prototype/knowledge/services/logic-apps.md new file mode 100644 index 0000000..7ec01c6 --- /dev/null +++ b/azext_prototype/knowledge/services/logic-apps.md @@ -0,0 +1,242 @@ +--- +service_namespace: Microsoft.Logic/workflows +display_name: Azure Logic Apps +--- + +# Azure Logic Apps +> Low-code workflow orchestration service for automating business processes and integrating with hundreds of connectors across cloud and on-premises systems. + +## When to Use + +- **System integration** -- connect SaaS applications, on-premises systems, and Azure services with pre-built connectors +- **Business process automation** -- approval workflows, document processing, data transformation pipelines +- **Event-driven orchestration** -- trigger workflows from Event Grid, Service Bus, HTTP, schedules, or file events +- **B2B integration** -- EDI, AS2, and enterprise application integration scenarios +- **API orchestration** -- fan-out/fan-in patterns, retry with backoff, conditional branching + +Prefer Logic Apps over Azure Functions when the workflow is connector-heavy and benefits from visual design. Use Functions for custom compute-intensive logic or sub-second latency requirements. Logic Apps (Standard) runs on App Service plan for VNet integration and dedicated compute. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Plan type | Consumption | Pay-per-execution; lowest cost for POC | +| Plan type (with VNet) | Standard (WS1) | Runs on App Service plan; supports VNet, stateful workflows | +| Managed identity | System-assigned | For connector authentication | +| State | Enabled | Workflow active on creation | +| Trigger | HTTP (manual) or Recurrence | Simplest trigger for POC | + +## Terraform Patterns + +### Basic Resource (Consumption) + +```hcl +resource "azapi_resource" "logic_app" { + type = "Microsoft.Logic/workflows@2019-05-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + properties = { + state = "Enabled" + definition = { + "$schema" = "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#" + contentVersion = "1.0.0.0" + triggers = { + manual = { + type = "Request" + kind = "Http" + inputs = { + schema = {} + } + } + } + actions = {} + outputs = {} + } + } + } + + tags = var.tags + + response_export_values = ["properties.accessEndpoint"] +} +``` + +### Basic Resource (Standard) + +```hcl +resource "azapi_resource" "logic_app_plan" { + type = "Microsoft.Web/serverfarms@2023-12-01" + name = var.plan_name + location = var.location + parent_id = var.resource_group_id + + body = { + kind = "elastic" + sku = { + name = "WS1" + tier = "WorkflowStandard" + } + properties = { + reserved = true + } + } + + tags = var.tags +} + +resource "azapi_resource" "logic_app_standard" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + kind = "functionapp,workflowapp" + properties = { + serverFarmId = azapi_resource.logic_app_plan.id + httpsOnly = true + siteConfig = { + minTlsVersion = "1.2" + appSettings = [ + { + name = "FUNCTIONS_EXTENSION_VERSION" + value = "~4" + }, + { + name = "FUNCTIONS_WORKER_RUNTIME" + value = "node" + }, + { + name = "AzureWebJobsStorage" + value = var.storage_connection_string + } + ] + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Logic App's system-assigned identity accessing other resources +# Example: grant Logic App access to Service Bus +resource "azapi_resource" "servicebus_sender_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.servicebus_namespace_id}${azapi_resource.logic_app.identity[0].principal_id}servicebus-sender") + parent_id = var.servicebus_namespace_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/69a216fc-b8fb-44d8-bc22-1f3c2cd27a39" # Azure Service Bus Data Sender + principalId = azapi_resource.logic_app.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource (Consumption) + +```bicep +@description('Name of the Logic App') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource logicApp 'Microsoft.Logic/workflows@2019-05-01' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + properties: { + state: 'Enabled' + definition: { + '$schema': 'https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#' + contentVersion: '1.0.0.0' + triggers: { + manual: { + type: 'Request' + kind: 'Http' + inputs: { + schema: {} + } + } + } + actions: {} + outputs: {} + } + } +} + +output id string = logicApp.id +output name string = logicApp.name +output accessEndpoint string = logicApp.properties.accessEndpoint +output principalId string = logicApp.identity.principalId +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the Logic App managed identity') +param principalId string + +@description('Service Bus namespace to grant access to') +param serviceBusNamespaceId string + +// Grant Logic App access to send messages to Service Bus +resource serviceBusSenderRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(serviceBusNamespaceId, principalId, '69a216fc-b8fb-44d8-bc22-1f3c2cd27a39') + scope: serviceBus + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '69a216fc-b8fb-44d8-bc22-1f3c2cd27a39') // Azure Service Bus Data Sender + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Consumption vs Standard confusion | Consumption is serverless (pay-per-run); Standard needs App Service plan and storage account | Choose Consumption for simple POC, Standard for VNet or stateful workflows | +| Connector authentication with keys | Secrets embedded in workflow definition | Use managed identity for connectors that support it | +| Infinite trigger loops | Workflow triggers itself repeatedly, consuming massive run costs | Add conditions to prevent re-triggering; use concurrency limits | +| Missing retry policies | Transient failures cause workflow to fail | Configure retry policies on actions (fixed, exponential, or custom intervals) | +| Large message handling | Consumption tier has 100 MB message limit | Use chunking or blob storage for large payloads | +| Not using managed connectors | Custom HTTP calls lose built-in retry, pagination, and throttling | Use managed connectors where available for built-in reliability | + +## Production Backlog Items + +- [ ] Migrate to Standard tier for VNet integration and dedicated compute +- [ ] Enable private endpoint for Standard tier workflows +- [ ] Configure diagnostic logging to Log Analytics workspace +- [ ] Set up monitoring alerts (failed runs, throttled actions, latency) +- [ ] Implement integration account for B2B scenarios (maps, schemas, partners) +- [ ] Configure concurrency and debatching limits for high-throughput triggers +- [ ] Review and optimize connector usage for cost (premium connectors cost more) +- [ ] Set up automated deployment pipeline for workflow definitions +- [ ] Enable Application Insights integration for end-to-end tracing diff --git a/azext_prototype/knowledge/services/machine-learning-compute.md b/azext_prototype/knowledge/services/machine-learning-compute.md new file mode 100644 index 0000000..e3c723d --- /dev/null +++ b/azext_prototype/knowledge/services/machine-learning-compute.md @@ -0,0 +1,191 @@ +--- +service_namespace: Microsoft.MachineLearningServices/workspaces/computes +display_name: Machine Learning Compute +depends_on: + - Microsoft.MachineLearningServices/workspaces +--- + +# Machine Learning Compute + +> A compute target within an Azure Machine Learning workspace for running training jobs, inference endpoints, or interactive notebooks. Includes compute instances, compute clusters, and attached computes. + +## When to Use +- **Compute instance**: Interactive development (Jupyter notebooks, VS Code remote) +- **Compute cluster**: Scalable training jobs that auto-scale to zero when idle +- **Managed online endpoint**: Real-time inference hosting (separate resource, not covered here) +- **Attached compute**: Use existing AKS, Databricks, or VMs as ML compute +- Every ML training job needs a compute target + +## POC Defaults +- **Compute instance**: Standard_DS3_v2 (4 vCPU, 14 GB RAM) +- **Compute cluster**: Standard_DS3_v2, min nodes 0, max nodes 2 +- **Idle seconds before scale down**: 1800 (30 minutes) +- **Identity**: System-assigned managed identity + +## Terraform Patterns + +### Basic Resource +```hcl +# Compute instance for development +resource "azapi_resource" "ml_compute_instance" { + type = "Microsoft.MachineLearningServices/workspaces/computes@2024-10-01" + name = var.compute_instance_name + parent_id = azapi_resource.ml_workspace.id + location = var.location + + body = { + properties = { + computeType = "ComputeInstance" + properties = { + vmSize = "Standard_DS3_v2" + enableNodePublicIp = false + idleTimeBeforeShutdown = "PT30M" + applicationSharingPolicy = "Personal" + } + } + } +} + +# Compute cluster for training +resource "azapi_resource" "ml_compute_cluster" { + type = "Microsoft.MachineLearningServices/workspaces/computes@2024-10-01" + name = var.cluster_name + parent_id = azapi_resource.ml_workspace.id + location = var.location + + body = { + properties = { + computeType = "AmlCompute" + properties = { + vmSize = "Standard_DS3_v2" + vmPriority = "Dedicated" + scaleSettings = { + minNodeCount = 0 + maxNodeCount = 2 + nodeIdleTimeBeforeScaleDown = "PT1800S" + } + enableNodePublicIp = false + } + } + } +} +``` + +### RBAC Assignment +```hcl +# Azure ML Data Scientist role allows submitting jobs and using computes. +# Azure ML Compute Operator role allows managing compute resources. +resource "azapi_resource" "ml_compute_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = var.role_assignment_name + parent_id = azapi_resource.ml_workspace.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/f6c7c914-8db3-469d-8ca1-694a8f32e121" + principalId = var.data_scientist_principal_id + principalType = "User" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param clusterName string +param location string +param vmSize string = 'Standard_DS3_v2' + +resource computeCluster 'Microsoft.MachineLearningServices/workspaces/computes@2024-10-01' = { + parent: mlWorkspace + name: clusterName + location: location + properties: { + computeType: 'AmlCompute' + properties: { + vmSize: vmSize + vmPriority: 'Dedicated' + scaleSettings: { + minNodeCount: 0 + maxNodeCount: 2 + nodeIdleTimeBeforeScaleDown: 'PT1800S' + } + enableNodePublicIp: false + } + } +} + +output computeId string = computeCluster.id +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +from azure.ai.ml import MLClient, command + +credential = DefaultAzureCredential() +ml_client = MLClient(credential, subscription_id, rg_name, workspace_name) + +# Submit a training job to the compute cluster +job = command( + code="./src", + command="python train.py --epochs 10 --lr 0.001", + environment="AzureML-sklearn-1.0-ubuntu20.04-py38-cpu:1", + compute=cluster_name, +) +returned_job = ml_client.jobs.create_or_update(job) +print(f"Job name: {returned_job.name}, Status: {returned_job.status}") +``` + +### C# +```csharp +using Azure.Identity; +using Azure.ResourceManager; +using Azure.ResourceManager.MachineLearning; + +var credential = new DefaultAzureCredential(); +var client = new ArmClient(credential); + +var workspace = client.GetMachineLearningWorkspaceResource( + MachineLearningWorkspaceResource.CreateResourceIdentifier( + subscriptionId, rgName, workspaceName)); + +var computes = workspace.GetMachineLearningComputes(); +await foreach (var compute in computes.GetAllAsync()) +{ + Console.WriteLine($"Compute: {compute.Data.Name}, Type: {compute.Data.Properties.ComputeType}"); +} +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { MachineLearningClient } from "@azure/arm-machinelearning"; + +const credential = new DefaultAzureCredential(); +const client = new MachineLearningClient(credential, subscriptionId); + +const computes = client.computeOperations.list(rgName, workspaceName); +for await (const compute of computes) { + console.log(`Compute: ${compute.name}, Type: ${compute.properties?.computeType}`); +} +``` + +## Common Pitfalls +- **Compute instance is single-user**: Compute instances are assigned to one user. Use `applicationSharingPolicy: "Personal"` and specify the assigned user. +- **Scale-down delay**: Even with `minNodeCount: 0`, nodes don't shut down immediately. The idle timeout controls when scale-down begins. +- **VNet integration requirements**: Disabling public IP (`enableNodePublicIp: false`) requires VNet integration and a private endpoint on the workspace. +- **Spot/low-priority preemption**: Using `vmPriority: "LowPriority"` saves costs but jobs may be preempted. Training scripts must support checkpointing. +- **Location must match workspace**: The compute location must match the parent workspace location. +- **Quota limits**: Compute creation fails if the subscription's regional VM quota is exhausted. Check quota before deploying large clusters. + +## Production Backlog Items +- GPU compute clusters for deep learning workloads +- Auto-scale policies based on job queue depth +- Managed identity for compute-to-data-store access +- VNet-integrated compute for network isolation +- Scheduled start/stop for compute instances diff --git a/azext_prototype/knowledge/services/machine-learning.md b/azext_prototype/knowledge/services/machine-learning.md new file mode 100644 index 0000000..bc70330 --- /dev/null +++ b/azext_prototype/knowledge/services/machine-learning.md @@ -0,0 +1,255 @@ +--- +service_namespace: Microsoft.MachineLearningServices/workspaces +display_name: Azure Machine Learning +--- + +# Azure Machine Learning +> Enterprise-grade platform for building, training, deploying, and managing machine learning models at scale, with MLOps capabilities, experiment tracking, and managed compute. + +## When to Use + +- **ML model training** -- train models at scale using managed compute clusters (CPU/GPU) +- **MLOps pipelines** -- automated ML workflows for data prep, training, evaluation, and deployment +- **Model registry** -- version control and governance for ML models +- **Managed endpoints** -- deploy models as real-time REST APIs or batch inference pipelines +- **Responsible AI** -- model explainability, fairness, and error analysis dashboards +- **AutoML** -- automated model selection and hyperparameter tuning +- **Notebook-based experimentation** -- Jupyter notebooks with managed compute instances + +Prefer Azure ML over Azure OpenAI when you need custom model training on your own data. Use Azure OpenAI for pre-trained language models (GPT, embeddings). Use Azure Databricks when ML is part of a larger data engineering and analytics platform. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Basic | No SLA; sufficient for experimentation | +| Compute instance | Standard_DS3_v2 | 4 vCores, 14 GiB RAM; for notebooks/dev | +| Compute cluster | Standard_DS3_v2, 0-2 nodes | Scale to 0 when idle to minimize cost | +| Storage account | Required | Workspace default storage for datasets and artifacts | +| Key Vault | Required | Workspace secrets management | +| Application Insights | Required | Experiment and endpoint monitoring | +| Container Registry | Optional | Created on first model deployment | +| Public network access | Enabled | Flag private endpoint as production backlog item | +| Managed identity | System-assigned (workspace) | Plus user-assigned for compute if needed | + +## Terraform Patterns + +### Basic Resource + +```hcl +# Prerequisites: Storage Account, Key Vault, App Insights must exist +resource "azapi_resource" "ml_workspace" { + type = "Microsoft.MachineLearningServices/workspaces@2024-04-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Basic" + tier = "Basic" + } + properties = { + friendlyName = var.friendly_name + storageAccount = var.storage_account_id + keyVault = var.key_vault_id + applicationInsights = var.app_insights_id + containerRegistry = null # Created on first model deployment + publicNetworkAccess = "Enabled" # Disable for production + v1LegacyMode = false + } + } + + tags = var.tags + + response_export_values = ["properties.workspaceId", "properties.discoveryUrl"] +} +``` + +### Compute Instance (Dev/Notebook) + +```hcl +resource "azapi_resource" "compute_instance" { + type = "Microsoft.MachineLearningServices/workspaces/computes@2024-04-01" + name = var.compute_instance_name + location = var.location + parent_id = azapi_resource.ml_workspace.id + + body = { + properties = { + computeType = "ComputeInstance" + properties = { + vmSize = "Standard_DS3_v2" + enableNodePublicIp = false + idleTimeBeforeShutdown = "PT30M" # Auto-shutdown after 30 min idle + } + } + } + + tags = var.tags +} +``` + +### Compute Cluster (Training) + +```hcl +resource "azapi_resource" "compute_cluster" { + type = "Microsoft.MachineLearningServices/workspaces/computes@2024-04-01" + name = var.cluster_name + location = var.location + parent_id = azapi_resource.ml_workspace.id + + body = { + properties = { + computeType = "AmlCompute" + properties = { + vmSize = "Standard_DS3_v2" + vmPriority = "LowPriority" # Cost savings for POC + scaleSettings = { + maxNodeCount = 2 + minNodeCount = 0 # Scale to 0 when idle + nodeIdleTimeBeforeScaleDown = "PT5M" + } + enableNodePublicIp = false + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# AzureML Data Scientist -- run experiments, manage models, submit jobs +resource "azapi_resource" "ml_data_scientist_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.ml_workspace.id}${var.managed_identity_principal_id}ml-data-scientist") + parent_id = azapi_resource.ml_workspace.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/f6c7c914-8db3-469d-8ca1-694a8f32e121" # AzureML Data Scientist + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Workspace identity needs access to storage, key vault, and ACR +resource "azapi_resource" "ml_storage_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}${azapi_resource.ml_workspace.identity[0].principal_id}storage-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor + principalId = azapi_resource.ml_workspace.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the ML workspace') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Friendly display name') +param friendlyName string = name + +@description('Storage account resource ID') +param storageAccountId string + +@description('Key Vault resource ID') +param keyVaultId string + +@description('Application Insights resource ID') +param applicationInsightsId string + +@description('Tags to apply') +param tags object = {} + +resource mlWorkspace 'Microsoft.MachineLearningServices/workspaces@2024-04-01' = { + name: name + location: location + tags: tags + identity: { + type: 'SystemAssigned' + } + sku: { + name: 'Basic' + tier: 'Basic' + } + properties: { + friendlyName: friendlyName + storageAccount: storageAccountId + keyVault: keyVaultId + applicationInsights: applicationInsightsId + publicNetworkAccess: 'Enabled' + v1LegacyMode: false + } +} + +output id string = mlWorkspace.id +output name string = mlWorkspace.name +output workspaceId string = mlWorkspace.properties.workspaceId +output principalId string = mlWorkspace.identity.principalId +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the user or service principal') +param principalId string + +// AzureML Data Scientist +resource mlDataScientistRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(mlWorkspace.id, principalId, 'f6c7c914-8db3-469d-8ca1-694a8f32e121') + scope: mlWorkspace + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f6c7c914-8db3-469d-8ca1-694a8f32e121') // AzureML Data Scientist + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Forgetting prerequisite resources | Workspace creation fails without Storage, Key Vault, App Insights | Create all three dependencies before the workspace | +| Compute left running | Compute instances charge per hour even when idle | Enable auto-shutdown (`idleTimeBeforeShutdown`) on compute instances | +| Using dedicated VMs for POC | Unnecessary cost for intermittent training | Use `LowPriority` VMs and scale-to-zero for training clusters | +| Not registering models | Trained models lost, no version control | Register models in the workspace model registry after training | +| Missing workspace identity RBAC | Workspace cannot access storage, key vault, or ACR | Grant workspace system-assigned identity roles on dependent resources | +| Public compute with sensitive data | Data exposed on public network | Disable `enableNodePublicIp` on compute instances and clusters | +| Large datasets in workspace storage | Slow upload, high storage costs | Use Azure Data Lake Storage and register as a datastore | + +## Production Backlog Items + +- [ ] Enable private endpoint and disable public network access +- [ ] Configure managed VNet for workspace (workspace-managed VNet isolation) +- [ ] Set up compute quotas and budgets to prevent cost overruns +- [ ] Enable diagnostic logging to Log Analytics workspace +- [ ] Configure model registry with approval workflows +- [ ] Set up CI/CD pipelines for MLOps (train, evaluate, deploy) +- [ ] Enable customer managed keys for encryption at rest +- [ ] Configure data access governance with workspace datastores +- [ ] Review and right-size compute SKUs based on training workload profiles +- [ ] Set up monitoring alerts (training job failures, endpoint latency, drift detection) +- [ ] Implement model monitoring for data drift and prediction quality diff --git a/azext_prototype/knowledge/services/managed-grafana.md b/azext_prototype/knowledge/services/managed-grafana.md new file mode 100644 index 0000000..facf56f --- /dev/null +++ b/azext_prototype/knowledge/services/managed-grafana.md @@ -0,0 +1,288 @@ +--- +service_namespace: Microsoft.Dashboard/grafana +display_name: Azure Managed Grafana +--- + +# Azure Managed Grafana +> Fully managed Grafana instance for building rich observability dashboards with native Azure Monitor, Azure Data Explorer, and Prometheus data source integrations. + +## When to Use + +- Building custom observability dashboards beyond Azure Monitor Workbooks +- Teams already familiar with Grafana for monitoring and visualization +- Correlating metrics from Azure Monitor, Prometheus, and custom data sources in a single pane +- Multi-cloud monitoring with Grafana's extensive data source plugin ecosystem +- NOT suitable for: alerting without dashboards (use Azure Monitor alerts directly), log querying (use Log Analytics), or application performance monitoring (use App Insights) + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Essential tier lacks some features; Standard recommended for POC | +| Zone redundancy | Disabled | Enable for production | +| API key access | Disabled | Use Entra ID authentication | +| Public network access | Enabled | Disable for production with private endpoints | +| Deterministic outbound IP | Disabled | Enable if data sources require IP allowlisting | +| Azure Monitor integration | Enabled | Auto-configured for the subscription | +| Grafana admin | Deploying principal | Assign via Grafana Admin role | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "grafana" { + type = "Microsoft.Dashboard/grafana@2023-09-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + zoneRedundancy = "Disabled" # Enable for production + publicNetworkAccess = "Enabled" # Disable for production + apiKey = "Disabled" + deterministicOutboundIP = "Disabled" + autoGeneratedDomainNameLabelScope = "TenantReuse" + grafanaIntegrations = { + azureMonitorWorkspaceIntegrations = [] + } + } + } + + tags = var.tags + + response_export_values = ["properties.endpoint"] +} +``` + +### With Azure Monitor Workspace (Prometheus) + +```hcl +resource "azapi_resource" "monitor_workspace" { + type = "Microsoft.Monitor/accounts@2023-04-03" + name = var.monitor_workspace_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = {} + } + + tags = var.tags +} + +resource "azapi_resource" "grafana_with_prometheus" { + type = "Microsoft.Dashboard/grafana@2023-09-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "SystemAssigned" + } + + body = { + sku = { + name = "Standard" + } + properties = { + publicNetworkAccess = "Enabled" + apiKey = "Disabled" + grafanaIntegrations = { + azureMonitorWorkspaceIntegrations = [ + { + azureMonitorWorkspaceResourceId = azapi_resource.monitor_workspace.id + } + ] + } + } + } + + tags = var.tags + + response_export_values = ["properties.endpoint"] +} +``` + +### RBAC Assignment + +```hcl +# Grafana Admin -- full admin access to the Grafana instance +resource "azapi_resource" "grafana_admin" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.grafana.id}${var.admin_principal_id}grafana-admin") + parent_id = azapi_resource.grafana.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/22926164-76b3-42b3-bc55-97df8dab3e41" # Grafana Admin + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grafana Viewer -- read-only dashboard access +resource "azapi_resource" "grafana_viewer" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.grafana.id}${var.viewer_principal_id}grafana-viewer") + parent_id = azapi_resource.grafana.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/60921a7e-fef1-4a43-9b16-a26c52ad4769" # Grafana Viewer + principalId = var.viewer_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Grant Grafana's managed identity Monitoring Reader on the subscription +# (required for Azure Monitor data source) +resource "azapi_resource" "monitoring_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "/subscriptions/${var.subscription_id}${azapi_resource.grafana.identity[0].principal_id}monitoring-reader") + parent_id = "/subscriptions/${var.subscription_id}" + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/43d0d8ad-25c7-4714-9337-8ba259a9fe05" # Monitoring Reader + principalId = azapi_resource.grafana.identity[0].principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "grafana_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.grafana.id + groupIds = ["grafana"] + } + } + ] + } + } + + tags = var.tags +} +``` + +Private DNS zone: `privatelink.grafana.azure.com` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param tags object = {} + +resource grafana 'Microsoft.Dashboard/grafana@2023-09-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard' + } + identity: { + type: 'SystemAssigned' + } + properties: { + zoneRedundancy: 'Disabled' + publicNetworkAccess: 'Enabled' + apiKey: 'Disabled' + deterministicOutboundIP: 'Disabled' + autoGeneratedDomainNameLabelScope: 'TenantReuse' + grafanaIntegrations: { + azureMonitorWorkspaceIntegrations: [] + } + } +} + +output id string = grafana.id +output name string = grafana.name +output endpoint string = grafana.properties.endpoint +output principalId string = grafana.identity.principalId +``` + +### RBAC Assignment + +```bicep +param adminPrincipalId string + +// Grafana Admin +resource grafanaAdmin 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(grafana.id, adminPrincipalId, '22926164-76b3-42b3-bc55-97df8dab3e41') + scope: grafana + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '22926164-76b3-42b3-bc55-97df8dab3e41') + principalId: adminPrincipalId + principalType: 'ServicePrincipal' + } +} + +// Monitoring Reader for Grafana's managed identity (subscription scope) +resource monitoringReader 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(subscription().id, grafana.identity.principalId, '43d0d8ad-25c7-4714-9337-8ba259a9fe05') + scope: subscription() + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '43d0d8ad-25c7-4714-9337-8ba259a9fe05') + principalId: grafana.identity.principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Not assigning Monitoring Reader to Grafana identity | Azure Monitor data source returns empty results | Grant Monitoring Reader on the subscription to Grafana's managed identity | +| Using API keys instead of Entra ID | Less secure, keys can leak | Keep `apiKey = "Disabled"` and use Entra RBAC roles | +| Not assigning Grafana RBAC roles to users | Users cannot access dashboards despite Azure access | Assign Grafana Admin/Editor/Viewer roles on the Grafana resource | +| Essential tier limitations | No enterprise plugins, limited alert rules, no SAML | Use Standard tier for POC; Essential only for basic viewing | +| Forgetting Log Analytics Reader role | Grafana cannot query Log Analytics data source | Grant Log Analytics Reader to Grafana's managed identity on the workspace | +| Dashboard export/import not planned | Dashboards lost if Grafana instance is recreated | Export dashboards as JSON; store in source control | +| Region availability | Managed Grafana not available in all Azure regions | Check region availability before deployment | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Private endpoint | P1 | Deploy private endpoint and disable public network access | +| Zone redundancy | P2 | Enable zone redundancy for high availability | +| Dashboard as code | P2 | Store dashboards in source control and deploy via CI/CD | +| Prometheus integration | P2 | Connect Azure Monitor Workspace for Prometheus metrics | +| Custom data sources | P3 | Configure additional data sources (Azure Data Explorer, Elasticsearch) | +| Alert rules | P2 | Configure Grafana alerting for critical metrics | +| SAML/SSO | P3 | Enable SAML authentication for enterprise SSO (Standard tier) | +| Deterministic outbound IP | P3 | Enable if data sources require IP allowlisting | +| Backup dashboards | P3 | Implement regular dashboard export and backup strategy | +| Team/folder permissions | P3 | Organize dashboards by team with folder-level permissions | diff --git a/azext_prototype/knowledge/services/managed-hsm.md b/azext_prototype/knowledge/services/managed-hsm.md new file mode 100644 index 0000000..4387dae --- /dev/null +++ b/azext_prototype/knowledge/services/managed-hsm.md @@ -0,0 +1,228 @@ +--- +service_namespace: Microsoft.KeyVault/managedHSMs +display_name: Azure Managed HSM +--- + +# Azure Managed HSM +> FIPS 140-2 Level 3 validated, fully managed hardware security module for cryptographic key management, providing single-tenant HSM pools with full administrative control over the security domain. + +## When to Use + +- Regulatory compliance requiring FIPS 140-2 Level 3 (Key Vault standard is Level 2) +- High-throughput cryptographic operations (TLS offloading, database encryption) +- Full control over the security domain (bring your own key, key sovereignty) +- Single-tenant HSM requirement for financial services, healthcare, or government +- Customer-managed key (CMK) encryption for Azure services requiring Level 3 +- NOT suitable for: general-purpose secret storage (use Key Vault), certificate management (use Key Vault), low-volume key operations (use Key Vault -- significantly cheaper), or application configuration (use App Configuration) + +**Cost warning**: Managed HSM is significantly more expensive than Key Vault ($4+ per HSM pool per hour). Use Key Vault for POCs unless Level 3 compliance is explicitly required. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard_B1 | Only available SKU | +| Initial admin count | 3 | Minimum recommended for security domain quorum | +| Security domain quorum | 2 of 3 | Number of keys needed to recover security domain | +| Network ACLs | Default allow | Restrict for production | +| Soft delete | Enabled (always) | Cannot be disabled; 90-day retention | +| Purge protection | Enabled | Recommended; prevents permanent deletion during retention | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "managed_hsm" { + type = "Microsoft.KeyVault/managedHSMs@2023-07-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + family = "B" + name = "Standard_B1" + } + properties = { + tenantId = var.tenant_id + initialAdminObjectIds = var.initial_admin_object_ids # List of AAD object IDs + enableSoftDelete = true + softDeleteRetentionInDays = 90 + enablePurgeProtection = true + publicNetworkAccess = "Enabled" # Disable for production + networkAcls = { + bypass = "AzureServices" + defaultAction = "Allow" # Deny for production + } + } + } + + tags = var.tags + + response_export_values = ["properties.hsmUri"] +} +``` + +### RBAC Assignment + +```hcl +# Managed HSM Crypto User -- use keys for encrypt/decrypt/sign/verify +resource "azapi_resource" "hsm_crypto_user" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.managed_hsm.id}${var.app_principal_id}hsm-crypto-user") + parent_id = azapi_resource.managed_hsm.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/21dbd100-6940-42c2-b190-5d6cb909625b" # Managed HSM Crypto User + principalId = var.app_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Managed HSM Crypto Officer -- manage keys (create, delete, rotate) +resource "azapi_resource" "hsm_crypto_officer" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.managed_hsm.id}${var.admin_principal_id}hsm-crypto-officer") + parent_id = azapi_resource.managed_hsm.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/515eb02d-2335-4d2d-92f2-b1cbdf9c3778" # Managed HSM Crypto Officer + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +```hcl +resource "azapi_resource" "hsm_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.managed_hsm.id + groupIds = ["managedhsm"] + } + } + ] + } + } + + tags = var.tags +} +``` + +Private DNS zone: `privatelink.managedhsm.azure.net` + +## Bicep Patterns + +### Basic Resource + +```bicep +param name string +param location string +param tenantId string +param initialAdminObjectIds array +param tags object = {} + +resource managedHsm 'Microsoft.KeyVault/managedHSMs@2023-07-01' = { + name: name + location: location + tags: tags + sku: { + family: 'B' + name: 'Standard_B1' + } + properties: { + tenantId: tenantId + initialAdminObjectIds: initialAdminObjectIds + enableSoftDelete: true + softDeleteRetentionInDays: 90 + enablePurgeProtection: true + publicNetworkAccess: 'Enabled' + networkAcls: { + bypass: 'AzureServices' + defaultAction: 'Allow' + } + } +} + +output id string = managedHsm.id +output name string = managedHsm.name +output hsmUri string = managedHsm.properties.hsmUri +``` + +### RBAC Assignment + +```bicep +param appPrincipalId string + +// Managed HSM Crypto User +resource hsmCryptoUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(managedHsm.id, appPrincipalId, '21dbd100-6940-42c2-b190-5d6cb909625b') + scope: managedHsm + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '21dbd100-6940-42c2-b190-5d6cb909625b') + principalId: appPrincipalId + principalType: 'ServicePrincipal' + } +} +``` + +## CRITICAL: Security Domain Activation + +After deploying a Managed HSM, it is in a **provisioned but not activated** state. You must download and activate the security domain before any key operations: + +```bash +# Download security domain (requires 3 RSA key pairs for quorum) +az keyvault security-domain download \ + --hsm-name \ + --sd-wrapping-keys key1.cer key2.cer key3.cer \ + --sd-quorum 2 \ + --security-domain-file sd.json +``` + +The HSM is **NOT usable** until the security domain is downloaded. This is a one-time operation. + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Not downloading security domain after creation | HSM is provisioned but unusable; no key operations work | Download security domain immediately after deployment | +| Using Managed HSM when Key Vault suffices | 50x+ cost difference (~$4/hr vs pennies per operation) | Use Key Vault unless FIPS 140-2 Level 3 is explicitly required | +| Losing security domain backup | HSM is unrecoverable if all admin access is lost | Store security domain file and key pairs in a secure offline location | +| Insufficient initial admin count | Cannot reach quorum for security domain recovery | Use at least 3 initial admins with quorum of 2 | +| Not enabling purge protection | Keys can be permanently deleted, breaking dependent services | Always enable purge protection for production | +| Confusing HSM RBAC with Key Vault RBAC | Different role names and role definition IDs | Use Managed HSM-specific roles (Crypto User, Crypto Officer) | +| Region availability | Managed HSM not available in all regions | Check region availability before planning deployment | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Private endpoint | P1 | Deploy private endpoint and restrict public network access | +| Network ACL lockdown | P1 | Set default action to Deny and allowlist specific subnets/IPs | +| Security domain backup | P1 | Securely store security domain backup and key pairs offline | +| Key rotation policy | P2 | Implement automated key rotation for all keys | +| Logging and monitoring | P2 | Enable diagnostic settings and route to Log Analytics | +| Disaster recovery | P2 | Plan and test security domain restore procedure | +| Audit access patterns | P3 | Review and minimize RBAC role assignments regularly | +| CMK integration | P2 | Configure Azure services to use HSM-backed customer-managed keys | +| Cost monitoring | P3 | Monitor HSM pool hours and key operation counts | diff --git a/azext_prototype/knowledge/services/managed-identity-federated-credential.md b/azext_prototype/knowledge/services/managed-identity-federated-credential.md new file mode 100644 index 0000000..867562d --- /dev/null +++ b/azext_prototype/knowledge/services/managed-identity-federated-credential.md @@ -0,0 +1,114 @@ +--- +service_namespace: Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials +display_name: Federated Identity Credential +depends_on: + - Microsoft.ManagedIdentity/userAssignedIdentities +--- + +# Federated Identity Credential + +> Establishes a trust relationship between a user-assigned managed identity and an external identity provider (GitHub Actions, Kubernetes, etc.) for workload identity federation. + +## When to Use +- CI/CD pipelines (GitHub Actions, Azure DevOps) that need to authenticate to Azure without storing secrets +- Kubernetes pods using workload identity to access Azure resources +- Any external workload that needs Azure access via OIDC token exchange + +## POC Defaults +- **Issuer**: GitHub Actions (`https://token.actions.githubusercontent.com`) or AKS OIDC issuer +- **Subject**: Repository and environment-specific (e.g., `repo:org/repo:ref:refs/heads/main`) +- **Audiences**: `["api://AzureADTokenExchange"]` + +## Terraform Patterns + +### GitHub Actions Federation +```hcl +resource "azapi_resource" "github_federation" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2023-07-31-preview" + name = "github-actions-main" + parent_id = azapi_resource.managed_identity.id + + body = { + properties = { + issuer = "https://token.actions.githubusercontent.com" + subject = "repo:${var.github_org}/${var.github_repo}:ref:refs/heads/main" + audiences = ["api://AzureADTokenExchange"] + } + } +} +``` + +### AKS Workload Identity +```hcl +resource "azapi_resource" "aks_federation" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2023-07-31-preview" + name = "aks-workload-identity" + parent_id = azapi_resource.managed_identity.id + + body = { + properties = { + issuer = var.aks_oidc_issuer_url + subject = "system:serviceaccount:${var.k8s_namespace}:${var.k8s_service_account}" + audiences = ["api://AzureADTokenExchange"] + } + } +} +``` + +### RBAC Assignment +```hcl +# The federated credential enables authentication. RBAC must still be +# assigned to the parent managed identity for resource access. +``` + +## Bicep Patterns + +### GitHub Actions Federation +```bicep +param githubOrg string +param githubRepo string + +resource federation 'Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2023-07-31-preview' = { + parent: managedIdentity + name: 'github-actions-main' + properties: { + issuer: 'https://token.actions.githubusercontent.com' + subject: 'repo:${githubOrg}/${githubRepo}:ref:refs/heads/main' + audiences: ['api://AzureADTokenExchange'] + } +} +``` + +## Application Code + +### Python +```python +# Federated credentials are used by CI/CD pipelines, not application code. +# In GitHub Actions, use azure/login with OIDC: +# - uses: azure/login@v2 +# with: +# client-id: ${{ secrets.AZURE_CLIENT_ID }} +# tenant-id: ${{ secrets.AZURE_TENANT_ID }} +# subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} +``` + +### C# +```csharp +// Not used in application code directly. See Python example for CI/CD usage. +``` + +### Node.js +```typescript +// Not used in application code directly. See Python example for CI/CD usage. +``` + +## Common Pitfalls +- **Subject must be exact**: The subject claim must exactly match what the external identity provider sends. For GitHub Actions, this includes the ref (branch/tag). +- **Max 20 federated credentials**: Each managed identity supports up to 20 federated credentials. +- **Audience must match**: The audience must be `api://AzureADTokenExchange` for Azure AD token exchange. +- **Not for application runtime**: Federated credentials are for CI/CD and external workloads, not for application code running in Azure (use managed identity directly). + +## Production Backlog Items +- Environment-specific federation (main, staging, production branches) +- Conditional access policies on the federated identity +- Monitoring of federated credential usage and token exchange failures diff --git a/azext_prototype/knowledge/services/managed-identity.md b/azext_prototype/knowledge/services/managed-identity.md new file mode 100644 index 0000000..92736d9 --- /dev/null +++ b/azext_prototype/knowledge/services/managed-identity.md @@ -0,0 +1,202 @@ +--- +service_namespace: Microsoft.ManagedIdentity/userAssignedIdentities +display_name: User-Assigned Managed Identity +--- + +# Azure Managed Identity +> Zero-credential authentication for Azure resources, providing automatically managed service principals in Azure AD that eliminate the need for secrets, keys, or certificates in application code. + +## When to Use + +- **Every Azure deployment** -- managed identity is the foundation for secret-free authentication across all Azure services +- **Application authentication to Azure services** -- App Service, Container Apps, Functions, VMs authenticating to Key Vault, Storage, databases, etc. +- **Cross-service RBAC** -- grant one Azure resource access to another without shared secrets +- **CI/CD pipelines** -- federated identity credentials for GitHub Actions and Azure DevOps without stored secrets + +**User-assigned** is strongly preferred for POCs because: (1) lifecycle is decoupled from the resource, (2) a single identity can be shared across multiple resources, (3) RBAC assignments survive resource recreation. + +Use **system-assigned** only when: the identity should be tightly coupled to the resource lifecycle, or the resource does not support user-assigned identities. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Type | User-assigned | Shared across app resources; survives resource recreation | +| Name convention | `id-{project}-{env}` | Follow naming strategy | +| RBAC model | Least privilege | Assign narrowest role per target resource | +| Federated credentials | Disabled | Enable only for CI/CD pipeline authentication | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "managed_identity" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31" + name = var.name + location = var.location + parent_id = var.resource_group_id + + tags = var.tags + + response_export_values = ["properties.principalId", "properties.clientId", "properties.tenantId"] +} +``` + +### Attach to a Resource + +```hcl +# Attach user-assigned identity to an App Service +resource "azapi_resource" "web_app" { + type = "Microsoft.Web/sites@2023-12-01" + name = var.app_name + location = var.location + parent_id = var.resource_group_id + + identity { + type = "UserAssigned" + identity_ids = [azapi_resource.managed_identity.id] + } + + body = { + properties = { + serverFarmId = var.plan_id + siteConfig = { + appSettings = [ + { + name = "AZURE_CLIENT_ID" + value = azapi_resource.managed_identity.output.properties.clientId + } + ] + } + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Grant the managed identity a role on a target resource +# Example: Key Vault Secrets User +resource "azapi_resource" "kv_secrets_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.key_vault_id}${azapi_resource.managed_identity.output.properties.principalId}kv-secrets-user") + parent_id = var.key_vault_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4633458b-17de-408a-b874-0445c86b69e6" # Key Vault Secrets User + principalId = azapi_resource.managed_identity.output.properties.principalId + principalType = "ServicePrincipal" + } + } +} + +# Example: Storage Blob Data Contributor +resource "azapi_resource" "storage_blob_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.storage_account_id}${azapi_resource.managed_identity.output.properties.principalId}storage-blob-contributor") + parent_id = var.storage_account_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe" # Storage Blob Data Contributor + principalId = azapi_resource.managed_identity.output.properties.principalId + principalType = "ServicePrincipal" + } + } +} +``` + +### Federated Identity Credential (GitHub Actions) + +```hcl +resource "azapi_resource" "github_federation" { + type = "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2023-01-31" + name = "github-actions" + parent_id = azapi_resource.managed_identity.id + + body = { + properties = { + issuer = "https://token.actions.githubusercontent.com" + subject = "repo:${var.github_org}/${var.github_repo}:ref:refs/heads/main" + audiences = ["api://AzureADTokenExchange"] + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the managed identity') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource managedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = { + name: name + location: location + tags: tags +} + +output id string = managedIdentity.id +output name string = managedIdentity.name +output principalId string = managedIdentity.properties.principalId +output clientId string = managedIdentity.properties.clientId +output tenantId string = managedIdentity.properties.tenantId +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity') +param principalId string + +@description('Key Vault resource to grant access to') +resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = { + name: keyVaultName +} + +// Key Vault Secrets User +resource kvSecretsRole 'Microsoft.Authorization/roleAssignments@2022-04-01' = { + name: guid(keyVault.id, principalId, '4633458b-17de-408a-b874-0445c86b69e6') + scope: keyVault + properties: { + roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6') // Key Vault Secrets User + principalId: principalId + principalType: 'ServicePrincipal' + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Using system-assigned when user-assigned is better | RBAC assignments lost when resource is recreated | Default to user-assigned; share across related resources | +| Forgetting `AZURE_CLIENT_ID` app setting | `DefaultAzureCredential` cannot select the correct identity on multi-identity resources | Always set `AZURE_CLIENT_ID` to the user-assigned identity's client ID | +| Over-privileged roles | Identity has more access than needed | Assign narrowest role: Reader, not Contributor; Secrets User, not Secrets Officer | +| Role assignment race conditions | Resource deployed before RBAC propagation completes | Add explicit dependency or `dependsOn` from the consuming resource to the role assignment | +| Missing `principalType` on role assignments | ARM must auto-detect type, causing intermittent failures | Always specify `principalType = "ServicePrincipal"` for managed identities | +| Not scoping RBAC to specific resources | Identity has broad access across resource group or subscription | Scope role assignments to individual resources, not resource groups | +| Orphaned identities | Unused identities clutter the tenant | Tag identities with the project they belong to; clean up during decommission | + +## Production Backlog Items + +- [ ] Audit all RBAC assignments for least-privilege compliance +- [ ] Configure federated identity credentials for CI/CD pipelines (eliminate stored secrets) +- [ ] Set up Azure Policy to enforce managed identity usage on supported resources +- [ ] Review and consolidate identities (reduce sprawl) +- [ ] Enable diagnostic settings on identity usage (sign-in logs) +- [ ] Document identity-to-resource mapping for operational runbooks +- [ ] Consider Managed Identity per environment (dev, staging, prod) for isolation diff --git a/azext_prototype/knowledge/services/monitor-account.md b/azext_prototype/knowledge/services/monitor-account.md new file mode 100644 index 0000000..a837d12 --- /dev/null +++ b/azext_prototype/knowledge/services/monitor-account.md @@ -0,0 +1,201 @@ +--- +service_namespace: Microsoft.Monitor/accounts +display_name: Azure Monitor Workspace (Managed Prometheus) +--- + +# Azure Monitor Workspace (Managed Prometheus) + +> Dedicated workspace for Azure Managed Prometheus metrics, providing a scalable time-series database for collecting, storing, and querying Prometheus metrics from Kubernetes and other workloads. + +## When to Use +- **AKS monitoring** -- collect Prometheus metrics from AKS clusters using Azure Monitor managed Prometheus +- **Grafana dashboards** -- pair with Azure Managed Grafana for Prometheus-native visualization +- **Multi-cluster monitoring** -- centralize Prometheus metrics from multiple AKS clusters +- **Custom metrics** -- store application-level Prometheus metrics alongside infrastructure metrics + +Azure Monitor workspaces are distinct from Log Analytics workspaces. They store Prometheus metrics in a time-series format optimized for PromQL queries. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Location | Same as AKS cluster | Minimize latency and egress costs | +| Default DCR | Auto-created | Data collection rule for Prometheus scraping | +| Retention | 18 months | Included; no configuration needed | +| Grafana | Azure Managed Grafana | Link for PromQL dashboards | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "monitor_account" { + type = "Microsoft.Monitor/accounts@2023-04-03" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = {} + } + + tags = var.tags + + response_export_values = [ + "properties.defaultIngestionSettings.dataCollectionEndpointResourceId", + "properties.defaultIngestionSettings.dataCollectionRuleResourceId", + "properties.metrics.prometheusQueryEndpoint" + ] +} +``` + +### RBAC Assignment + +```hcl +# Monitoring Data Reader -- for querying Prometheus metrics (Grafana) +resource "azapi_resource" "monitoring_data_reader" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.monitor_account.id}-${var.grafana_principal_id}-data-reader") + parent_id = azapi_resource.monitor_account.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/b0d8363b-8ddd-447d-831f-62ca05bff136" + principalId = var.grafana_principal_id + principalType = "ServicePrincipal" + } + } +} + +# Monitoring Contributor -- for managing the workspace +resource "azapi_resource" "monitoring_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.monitor_account.id}-${var.principal_id}-monitoring-contributor") + parent_id = azapi_resource.monitor_account.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/749f88d5-cbae-40b8-bcfc-e573ddc772fa" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Azure Monitor workspace') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +param tags object = {} + +resource monitorAccount 'Microsoft.Monitor/accounts@2023-04-03' = { + name: name + location: location + tags: tags + properties: {} +} + +output id string = monitorAccount.id +output prometheusQueryEndpoint string = monitorAccount.properties.metrics.prometheusQueryEndpoint +output defaultDcrId string = monitorAccount.properties.defaultIngestionSettings.dataCollectionRuleResourceId +``` + +## Application Code + +### Python + +```python +# Applications expose Prometheus metrics; the Azure Monitor agent scrapes them. +# No Azure SDK needed -- use standard Prometheus client libraries. +from prometheus_client import Counter, Histogram, start_http_server + +REQUEST_COUNT = Counter("http_requests_total", "Total HTTP requests", ["method", "endpoint"]) +REQUEST_LATENCY = Histogram("http_request_duration_seconds", "Request latency", ["endpoint"]) + +# Start metrics endpoint for scraping +start_http_server(8080) + +# In your request handler: +REQUEST_COUNT.labels(method="GET", endpoint="/api/items").inc() +with REQUEST_LATENCY.labels(endpoint="/api/items").time(): + pass # handle request +``` + +### C# + +```csharp +// Use prometheus-net library to expose metrics +// Install: dotnet add package prometheus-net.AspNetCore +using Prometheus; + +var builder = WebApplication.CreateBuilder(args); +var app = builder.Build(); + +// Add Prometheus metrics middleware +app.UseHttpMetrics(); // Auto-tracks HTTP request metrics +app.MapMetrics(); // Exposes /metrics endpoint + +var requestCounter = Metrics.CreateCounter( + "http_requests_total", "Total HTTP requests", + new CounterConfiguration { LabelNames = new[] { "method", "endpoint" } }); + +requestCounter.WithLabels("GET", "/api/items").Inc(); +app.Run(); +``` + +### Node.js + +```typescript +// Use prom-client library to expose metrics +// Install: npm install prom-client +import { Counter, Histogram, collectDefaultMetrics, register } from "prom-client"; + +collectDefaultMetrics(); + +const requestCount = new Counter({ + name: "http_requests_total", + help: "Total HTTP requests", + labelNames: ["method", "endpoint"], +}); + +const requestLatency = new Histogram({ + name: "http_request_duration_seconds", + help: "Request latency", + labelNames: ["endpoint"], +}); + +// Expose /metrics endpoint +app.get("/metrics", async (req, res) => { + res.set("Content-Type", register.contentType); + res.end(await register.metrics()); +}); +``` + +## Common Pitfalls + +1. **Not the same as Log Analytics workspace** -- `Microsoft.Monitor/accounts` is for Prometheus metrics. `Microsoft.OperationalInsights/workspaces` is for logs. They are different resources with different APIs. +2. **Region availability** -- Azure Monitor workspaces are not available in all regions. Check regional availability before deployment. +3. **Grafana must have Data Reader role** -- Azure Managed Grafana needs `Monitoring Data Reader` role on the workspace to query metrics. Missing this causes "no data" in dashboards. +4. **Data collection rule configuration** -- The workspace auto-creates a default DCR, but you must configure the AKS cluster to use it (via `Microsoft.ContainerService/managedClusters` monitoring addon or DCR association). +5. **Metric cardinality** -- High-cardinality labels (user IDs, request IDs) cause metric explosion and storage costs. Use bounded label values. +6. **Ingestion latency** -- Metrics have a 1-3 minute ingestion delay. Dashboards show slightly stale data. This is normal for managed Prometheus. +7. **PromQL compatibility** -- Azure Managed Prometheus supports most PromQL functions but some advanced features (exemplars, native histograms) may have limitations. + +## Production Backlog Items + +- [ ] Link to Azure Managed Grafana with Monitoring Data Reader RBAC +- [ ] Configure data collection rules for custom metric scraping targets +- [ ] Set up recording rules for frequently-used PromQL aggregations +- [ ] Configure alert rules using Prometheus alert syntax +- [ ] Enable multi-cluster metric collection with appropriate labels +- [ ] Optimize metric cardinality to control storage costs +- [ ] Import community Grafana dashboards for common workloads +- [ ] Configure remote-write from self-hosted Prometheus if needed diff --git a/azext_prototype/knowledge/services/mysql-flexible-administrator.md b/azext_prototype/knowledge/services/mysql-flexible-administrator.md new file mode 100644 index 0000000..89ccc5f --- /dev/null +++ b/azext_prototype/knowledge/services/mysql-flexible-administrator.md @@ -0,0 +1,143 @@ +--- +service_namespace: Microsoft.DBforMySQL/flexibleServers/administrators +display_name: MySQL Flexible Server Administrator +depends_on: + - Microsoft.DBforMySQL/flexibleServers +--- + +# MySQL Flexible Server Administrator + +> Configures Microsoft Entra ID (Azure AD) authentication administrators on a MySQL Flexible Server, enabling passwordless managed identity access. + +## When to Use +- Enable Entra ID authentication for passwordless connections from Azure services +- Assign a managed identity or user principal as the MySQL server administrator +- Required before any Entra ID token-based connections can be established +- Use alongside local MySQL password authentication for POC convenience + +## POC Defaults +- **Principal type**: ServicePrincipal (for managed identity) +- **Identity type**: The server must have a user-assigned managed identity configured +- **Administrator type**: ActiveDirectory + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "mysql_ad_admin" { + type = "Microsoft.DBforMySQL/flexibleServers/administrators@2023-12-30" + name = "ActiveDirectory" + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + administratorType = "ActiveDirectory" + identityResourceId = azapi_resource.user_identity.id + login = var.admin_login_name + sid = var.admin_principal_id + tenantId = var.tenant_id + } + } +} +``` + +### RBAC Assignment +```hcl +# The administrator identity is set at the MySQL level, not via Azure RBAC. +# The server needs a user-assigned managed identity for Entra auth to work. +# After deployment, the Entra admin creates additional MySQL users: +# CREATE AADUSER '' IDENTIFIED BY ''; +# GRANT ALL ON mydb.* TO ''; +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param adminLogin string +param adminSid string +param identityResourceId string +param tenantId string = tenant().tenantId + +resource mysqlAdmin 'Microsoft.DBforMySQL/flexibleServers/administrators@2023-12-30' = { + parent: mysqlServer + name: 'ActiveDirectory' + properties: { + administratorType: 'ActiveDirectory' + identityResourceId: identityResourceId + login: adminLogin + sid: adminSid + tenantId: tenantId + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +import mysql.connector + +credential = DefaultAzureCredential() +token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") + +conn = mysql.connector.connect( + host=".mysql.database.azure.com", + user="", + password=token.token, + database="mydb", + ssl_ca="/path/to/DigiCertGlobalRootCA.crt.pem" +) +cursor = conn.cursor() +cursor.execute("SELECT VERSION()") +print(cursor.fetchone()) +conn.close() +``` + +### C# +```csharp +using Azure.Identity; +using MySqlConnector; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://ossrdbms-aad.database.windows.net/.default" })); + +var connStr = $"Server=.mysql.database.azure.com;Database=mydb;User Id=;Password={token.Token};SslMode=Required"; +await using var conn = new MySqlConnection(connStr); +await conn.OpenAsync(); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import mysql from "mysql2/promise"; + +const credential = new DefaultAzureCredential(); +const token = await credential.getToken("https://ossrdbms-aad.database.windows.net/.default"); + +const conn = await mysql.createConnection({ + host: ".mysql.database.azure.com", + user: "", + password: token.token, + database: "mydb", + ssl: { rejectUnauthorized: true }, +}); +const [rows] = await conn.execute("SELECT VERSION()"); +console.log(rows); +await conn.end(); +``` + +## Common Pitfalls +- **User-assigned identity required**: Unlike PostgreSQL, MySQL Flexible Server requires a user-assigned managed identity on the server resource itself for Entra admin to function. +- **Resource name must be 'ActiveDirectory'**: The administrator resource name is always the literal string `ActiveDirectory`, not an object ID. +- **identityResourceId is mandatory**: The full resource ID of the user-assigned managed identity must be provided; system-assigned identity alone is insufficient. +- **Token scope same as PostgreSQL**: Use `https://ossrdbms-aad.database.windows.net/.default` for both MySQL and PostgreSQL Entra auth. +- **SSL certificate required**: MySQL clients need the DigiCert Global Root CA certificate for SSL connections. + +## Production Backlog Items +- Enable Entra-only authentication (disable MySQL native auth) +- Automate MySQL AADUSER creation for application managed identities +- Configure audit logging for Entra admin operations +- Certificate rotation strategy for SSL connections diff --git a/azext_prototype/knowledge/services/mysql-flexible-firewall-rule.md b/azext_prototype/knowledge/services/mysql-flexible-firewall-rule.md new file mode 100644 index 0000000..2fe5fc5 --- /dev/null +++ b/azext_prototype/knowledge/services/mysql-flexible-firewall-rule.md @@ -0,0 +1,103 @@ +--- +service_namespace: Microsoft.DBforMySQL/flexibleServers/firewallRules +display_name: MySQL Flexible Server Firewall Rule +depends_on: + - Microsoft.DBforMySQL/flexibleServers +--- + +# MySQL Flexible Server Firewall Rule + +> Controls which IP addresses can connect to a MySQL Flexible Server over its public endpoint. Required for public access mode servers. + +## When to Use +- Allow Azure services to connect via the special 0.0.0.0 rule +- Allow specific developer IPs for administrative access during POC +- Not needed when server uses VNet integration (private access mode) +- Required for any external connectivity to a public-access MySQL server + +## POC Defaults +- **AllowAzureServices**: 0.0.0.0 to 0.0.0.0 (enables managed identity access from Azure services) +- **Developer IP rules**: Added as needed for local development + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "mysql_firewall_allow_azure" { + type = "Microsoft.DBforMySQL/flexibleServers/firewallRules@2023-12-30" + name = "AllowAzureServices" + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + startIpAddress = "0.0.0.0" + endIpAddress = "0.0.0.0" + } + } +} + +resource "azapi_resource" "mysql_firewall_dev" { + type = "Microsoft.DBforMySQL/flexibleServers/firewallRules@2023-12-30" + name = "AllowDevIP" + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + startIpAddress = var.dev_ip + endIpAddress = var.dev_ip + } + } +} +``` + +### RBAC Assignment +```hcl +# Firewall rule management requires Contributor role on the parent Flexible Server. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource firewallAllowAzure 'Microsoft.DBforMySQL/flexibleServers/firewallRules@2023-12-30' = { + parent: mysqlServer + name: 'AllowAzureServices' + properties: { + startIpAddress: '0.0.0.0' + endIpAddress: '0.0.0.0' + } +} + +resource firewallDevIp 'Microsoft.DBforMySQL/flexibleServers/firewallRules@2023-12-30' = { + parent: mysqlServer + name: 'AllowDevIP' + properties: { + startIpAddress: devIpAddress + endIpAddress: devIpAddress + } +} +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **0.0.0.0 allows ALL Azure services**: This rule permits traffic from any Azure subscription, not just yours. Use VNet integration for production. +- **Public access must be enabled**: Firewall rules only apply when the server is in public access mode. VNet-integrated servers ignore them. +- **IP ranges, not CIDR**: MySQL Flexible Server firewall rules use start/end IP addresses, not CIDR notation. +- **Rule propagation delay**: Firewall rule changes can take several minutes to propagate. +- **No interaction with VNet rules**: If the server is created with private access, you cannot add firewall rules at all — the networking mode is immutable after creation. + +## Production Backlog Items +- Remove 0.0.0.0 rule and migrate to VNet integration or private endpoints +- Implement IP range restrictions for admin access via VPN +- Automate firewall rule cleanup tied to developer offboarding +- Enable firewall rule change auditing via Azure Activity Log diff --git a/azext_prototype/knowledge/services/mysql-flexible.md b/azext_prototype/knowledge/services/mysql-flexible.md new file mode 100644 index 0000000..62ebd76 --- /dev/null +++ b/azext_prototype/knowledge/services/mysql-flexible.md @@ -0,0 +1,244 @@ +--- +service_namespace: Microsoft.DBforMySQL/flexibleServers +display_name: Azure MySQL Flexible Server +--- + +# Azure Database for MySQL Flexible Server +> Fully managed MySQL database service with flexible compute and storage scaling, built-in high availability, and automated backups. + +## When to Use + +- **MySQL workloads** -- teams with MySQL expertise or existing MySQL applications +- **WordPress / PHP applications** -- MySQL is the default database for WordPress and many PHP frameworks +- **Open-source CMS platforms** -- Drupal, Joomla, Magento, and other MySQL-native applications +- **Migration from on-premises MySQL** -- near drop-in compatibility with MySQL 5.7 and 8.0 +- **Cost-sensitive relational workloads** -- Burstable tier starts lower than PostgreSQL equivalent + +Choose MySQL Flexible Server over Azure SQL for MySQL-native applications. Choose PostgreSQL Flexible Server when the team prefers PostgreSQL or needs extensions like pgvector. Choose Azure SQL for .NET-heavy stacks or SQL Server-specific features. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Burstable B1ms | 1 vCore, 2 GiB RAM; lowest cost for POC | +| Storage | 20 GiB | Minimum; auto-grow enabled | +| MySQL version | 8.0 | Latest stable | +| High availability | Disabled | POC doesn't need zone-redundant HA | +| Backup retention | 7 days | Default; sufficient for POC | +| Authentication | MySQL auth + AAD | AAD for app, MySQL auth for admin bootstrap | +| Public network access | Enabled | Flag private access as production backlog item | +| SSL enforcement | Required | `require_secure_transport = ON` | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "mysql_server" { + type = "Microsoft.DBforMySQL/flexibleServers@2023-12-30" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_B1ms" + tier = "Burstable" + } + properties = { + version = "8.0.21" + administratorLogin = var.admin_username + administratorLoginPassword = var.admin_password # Store in Key Vault + storage = { + storageSizeGB = 20 + autoGrow = "Enabled" + autoIoScaling = "Enabled" + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" # Enable for production + } + highAvailability = { + mode = "Disabled" # Enable for production + } + network = { + publicNetworkAccess = "Enabled" # Disable for production + } + } + } + + tags = var.tags + + response_export_values = ["properties.fullyQualifiedDomainName"] +} +``` + +### Firewall Rule (POC convenience) + +```hcl +resource "azapi_resource" "mysql_firewall_allow_azure" { + type = "Microsoft.DBforMySQL/flexibleServers/firewallRules@2023-12-30" + name = "AllowAzureServices" + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + startIpAddress = "0.0.0.0" + endIpAddress = "0.0.0.0" + } + } +} +``` + +### AAD Administrator + +```hcl +resource "azapi_resource" "mysql_aad_admin" { + type = "Microsoft.DBforMySQL/flexibleServers/administrators@2023-12-30" + name = var.managed_identity_principal_id + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + administratorType = "ActiveDirectory" + identityResourceId = var.managed_identity_id + login = var.aad_admin_login + sid = var.managed_identity_principal_id + tenantId = var.tenant_id + } + } +} +``` + +### RBAC Assignment + +```hcl +# MySQL Flexible Server does not use Azure RBAC for data-plane access. +# Data-plane access is controlled via MySQL GRANT statements after AAD admin setup. +# The managed identity authenticates via AAD token, then MySQL GRANTs control permissions. +# +# Control-plane RBAC example: grant deployment identity Contributor on the server +resource "azapi_resource" "mysql_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.mysql_server.id}${var.managed_identity_principal_id}mysql-contributor") + parent_id = azapi_resource.mysql_server.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the MySQL server') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Administrator login name') +param administratorLogin string + +@secure() +@description('Administrator login password') +param administratorLoginPassword string + +@description('Tags to apply') +param tags object = {} + +resource mysqlServer 'Microsoft.DBforMySQL/flexibleServers@2023-12-30' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard_B1ms' + tier: 'Burstable' + } + properties: { + version: '8.0.21' + administratorLogin: administratorLogin + administratorLoginPassword: administratorLoginPassword + storage: { + storageSizeGB: 20 + autoGrow: 'Enabled' + autoIoScaling: 'Enabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + highAvailability: { + mode: 'Disabled' + } + network: { + publicNetworkAccess: 'Enabled' + } + } +} + +output id string = mysqlServer.id +output name string = mysqlServer.name +output fqdn string = mysqlServer.properties.fullyQualifiedDomainName +``` + +### RBAC Assignment + +```bicep +@description('Principal ID of the managed identity for AAD admin') +param principalId string + +@description('Login name for the AAD admin') +param aadAdminLogin string + +@description('Managed identity resource ID') +param managedIdentityId string + +@description('Tenant ID') +param tenantId string + +resource mysqlAadAdmin 'Microsoft.DBforMySQL/flexibleServers/administrators@2023-12-30' = { + parent: mysqlServer + name: principalId + properties: { + administratorType: 'ActiveDirectory' + identityResourceId: managedIdentityId + login: aadAdminLogin + sid: principalId + tenantId: tenantId + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Using connection strings with passwords | Secrets in config, rotation burden | Configure AAD admin and use `DefaultAzureCredential` token for MySQL auth | +| Burstable tier CPU credits exhaustion | Performance degrades to baseline after sustained load | Monitor CPU credit balance; upgrade to General Purpose for sustained workloads | +| Missing SSL enforcement | Connections unencrypted in transit | Ensure `require_secure_transport = ON` (default); use `ssl-mode=REQUIRED` in connection strings | +| Storage auto-grow disabled | Server becomes read-only when storage is full | Enable `autoGrow` on storage configuration | +| Wrong MySQL version string | Deployment fails with invalid version error | Use exact version: `8.0.21` or `5.7` (not just `8.0`) | +| Firewall 0.0.0.0 rule in production | All Azure services can connect | Use VNet integration or private endpoints for production | +| Not creating application database | App tries to use system database | Create application-specific database via MySQL GRANT after server provisioning | + +## Production Backlog Items + +- [ ] Enable private access (VNet integration) and disable public network access +- [ ] Enable zone-redundant high availability +- [ ] Upgrade to General Purpose or Business Critical tier for production workloads +- [ ] Enable geo-redundant backup for disaster recovery +- [ ] Configure read replicas for read-heavy workloads +- [ ] Set up monitoring alerts (CPU, memory, storage, connections, slow queries) +- [ ] Enable slow query log and audit log for diagnostics +- [ ] Configure diagnostic logging to Log Analytics workspace +- [ ] Review and tune server parameters (innodb_buffer_pool_size, max_connections) +- [ ] Implement connection pooling in application code +- [ ] Set up automated maintenance window during off-peak hours diff --git a/azext_prototype/knowledge/services/nat-gateway.md b/azext_prototype/knowledge/services/nat-gateway.md new file mode 100644 index 0000000..99edd4c --- /dev/null +++ b/azext_prototype/knowledge/services/nat-gateway.md @@ -0,0 +1,265 @@ +--- +service_namespace: Microsoft.Network/natGateways +display_name: Azure NAT Gateway +--- + +# Azure NAT Gateway +> Fully managed, highly resilient outbound-only network address translation service providing predictable SNAT ports and static public IP addresses for outbound internet connectivity. + +## When to Use + +- **Predictable outbound IPs** -- when downstream services whitelist specific IP addresses +- **SNAT port exhaustion prevention** -- replaces default outbound access with dedicated SNAT ports +- **Standard Load Balancer backends** -- VMs behind Standard LB need explicit outbound connectivity +- **Container-based workloads** -- Container Apps and AKS nodes making many outbound connections +- **API integrations** -- calling third-party APIs that require IP-based allow-listing +- NOT suitable for: inbound traffic (use Load Balancer or Application Gateway) or cross-region scenarios + +NAT Gateway is a **subnet-level** service -- associate it with subnets that need outbound internet access. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Only available SKU | +| Idle timeout | 4 minutes | Default; increase for long-lived connections | +| Public IPs | 1 | Each IP provides ~64,000 SNAT ports | +| Public IP prefixes | None | Use for contiguous IP ranges | +| Availability zones | Zone-redundant | Automatic in supported regions | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "nat_pip" { + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "nat_gateway" { + type = "Microsoft.Network/natGateways@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + idleTimeoutInMinutes = 4 + publicIpAddresses = [ + { + id = azapi_resource.nat_pip.id + } + ] + } + } + + tags = var.tags + + response_export_values = ["*"] +} +``` + +### Associate NAT Gateway with Subnet + +```hcl +# Associate NAT Gateway with a workload subnet +resource "azapi_update_resource" "subnet_nat" { + type = "Microsoft.Network/virtualNetworks/subnets@2024-01-01" + resource_id = var.workload_subnet_id + + body = { + properties = { + addressPrefix = var.workload_subnet_prefix + natGateway = { + id = azapi_resource.nat_gateway.id + } + } + } +} +``` + +### Multiple Public IPs for Scale + +```hcl +resource "azapi_resource" "nat_pips" { + for_each = toset(["1", "2", "3"]) + + type = "Microsoft.Network/publicIPAddresses@2024-01-01" + name = "pip-${var.name}-${each.key}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + } + } + + tags = var.tags +} + +resource "azapi_resource" "nat_gateway_scaled" { + type = "Microsoft.Network/natGateways@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + idleTimeoutInMinutes = 10 + publicIpAddresses = [ + for pip in azapi_resource.nat_pips : { + id = pip.id + } + ] + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor for NAT Gateway management +resource "azapi_resource" "nat_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.nat_gateway.id}-${var.admin_principal_id}-network-contributor") + parent_id = azapi_resource.nat_gateway.id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +NAT Gateway does not use private endpoints -- it provides outbound internet connectivity for subnets. It operates transparently at the subnet level. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the NAT Gateway') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Idle timeout in minutes') +param idleTimeoutInMinutes int = 4 + +@description('Tags to apply') +param tags object = {} + +resource natPip 'Microsoft.Network/publicIPAddresses@2024-01-01' = { + name: 'pip-${name}' + location: location + sku: { + name: 'Standard' + } + properties: { + publicIPAllocationMethod: 'Static' + } + tags: tags +} + +resource natGateway 'Microsoft.Network/natGateways@2024-01-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard' + } + properties: { + idleTimeoutInMinutes: idleTimeoutInMinutes + publicIpAddresses: [ + { + id: natPip.id + } + ] + } +} + +output id string = natGateway.id +output publicIpAddress string = natPip.properties.ipAddress +``` + +### Subnet Association + +```bicep +@description('Existing VNet name') +param vnetName string + +@description('Subnet name to associate') +param subnetName string + +@description('Subnet address prefix') +param subnetPrefix string + +resource subnet 'Microsoft.Network/virtualNetworks/subnets@2024-01-01' = { + name: '${vnetName}/${subnetName}' + properties: { + addressPrefix: subnetPrefix + natGateway: { + id: natGateway.id + } + } +} +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Not associating with subnet | NAT Gateway has no effect until linked to a subnet | Explicitly update subnet properties with `natGateway.id` | +| Conflict with LB outbound rules | Both NAT Gateway and LB outbound rules defined | NAT Gateway takes precedence; remove LB outbound rules to avoid confusion | +| Using Basic SKU public IPs | Deployment fails; NAT Gateway requires Standard | Always use Standard SKU public IPs | +| Idle timeout too short | Long-running HTTP connections or downloads fail | Increase `idleTimeoutInMinutes` for workloads with long connections | +| Not enough public IPs | SNAT port exhaustion under high concurrency | Each public IP provides ~64K ports; add more IPs for scale | +| AzureBastionSubnet association | Bastion does not support NAT Gateway | Do not associate NAT Gateway with the AzureBastionSubnet | +| AzureFirewallSubnet association | Firewall does not support NAT Gateway | Do not associate NAT Gateway with the AzureFirewallSubnet | +| Gateway subnet association | VPN/ExpressRoute gateways have their own outbound path | Do not associate NAT Gateway with the GatewaySubnet | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Multiple public IPs | P2 | Add public IPs based on outbound connection requirements (~64K ports per IP) | +| Public IP prefix | P3 | Use a public IP prefix for contiguous IP ranges for firewall allow-listing | +| Idle timeout tuning | P3 | Adjust idle timeout based on observed connection patterns | +| Monitoring | P2 | Enable NAT Gateway metrics (SNAT port usage, dropped packets) in Azure Monitor | +| Subnet coverage | P1 | Ensure all workload subnets requiring outbound access have NAT Gateway associated | +| Documentation | P3 | Document outbound public IPs for third-party API allow-listing | +| Diagnostic logging | P2 | Enable resource logs for connection tracking and troubleshooting | +| Cost review | P3 | Review NAT Gateway costs vs. LB outbound rules for cost optimization | diff --git a/azext_prototype/knowledge/services/network-connection.md b/azext_prototype/knowledge/services/network-connection.md new file mode 100644 index 0000000..2e6aac8 --- /dev/null +++ b/azext_prototype/knowledge/services/network-connection.md @@ -0,0 +1,154 @@ +--- +service_namespace: Microsoft.Network/connections +display_name: Virtual Network Gateway Connection +--- + +# Virtual Network Gateway Connection + +> Logical link between a Virtual Network Gateway and another gateway (VPN site-to-site, VNet-to-VNet) or an ExpressRoute circuit, establishing encrypted tunnel or private circuit connectivity. + +## When to Use +- **Site-to-site VPN** -- connect on-premises network to Azure VNet over IPsec/IKE tunnel +- **VNet-to-VNet** -- connect two Azure VNets across regions or subscriptions via VPN gateways +- **ExpressRoute connection** -- link a VNet gateway to an ExpressRoute circuit for private connectivity +- Every VPN or ExpressRoute gateway requires at least one connection resource to route traffic + +Choose S2S VPN for cost-effective hybrid POC connectivity. Choose ExpressRoute connections for production-grade bandwidth and latency. VNet-to-VNet connections are alternatives to VNet peering when encryption is required. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Connection type | IPsec (S2S) | Most common for hybrid POC | +| IPsec/IKE policy | Default | Azure-managed; custom for compliance | +| Shared key | Strong random | Pre-shared key for IPsec authentication | +| Connection protocol | IKEv2 | Preferred over IKEv1 | +| Enable BGP | false | Static routes for simple POC; BGP for production | +| DPD timeout | 45 seconds | Dead Peer Detection default | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "vpn_connection" { + type = "Microsoft.Network/connections@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + connectionType = "IPsec" # or "Vnet2Vnet", "ExpressRoute" + virtualNetworkGateway1 = { + id = var.vnet_gateway_id + } + localNetworkGateway2 = { + id = var.local_network_gateway_id # For S2S only + } + sharedKey = var.shared_key # Store in Key Vault + enableBgp = false + useLocalAzureIpAddress = false + usePolicyBasedTrafficSelectors = false + connectionProtocol = "IKEv2" + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor on the resource group covers connection management +resource "azapi_resource" "network_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.resource_group_id}-${var.principal_id}-network-contributor") + parent_id = var.resource_group_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" + principalId = var.principal_id + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Connection name') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('VNet gateway resource ID') +param vnetGatewayId string + +@description('Local network gateway resource ID') +param localNetworkGatewayId string + +@secure() +@description('Pre-shared key for IPsec') +param sharedKey string + +param tags object = {} + +resource vpnConnection 'Microsoft.Network/connections@2024-01-01' = { + name: name + location: location + tags: tags + properties: { + connectionType: 'IPsec' + virtualNetworkGateway1: { + id: vnetGatewayId + } + localNetworkGateway2: { + id: localNetworkGatewayId + } + sharedKey: sharedKey + enableBgp: false + connectionProtocol: 'IKEv2' + } +} + +output id string = vpnConnection.id +output connectionStatus string = vpnConnection.properties.connectionStatus +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. VPN/ExpressRoute connections operate at the network layer; applications connect to Azure resources using their standard endpoints. + +### C# +Infrastructure -- transparent to application code. VPN/ExpressRoute connections operate at the network layer; applications connect to Azure resources using their standard endpoints. + +### Node.js +Infrastructure -- transparent to application code. VPN/ExpressRoute connections operate at the network layer; applications connect to Azure resources using their standard endpoints. + +## Common Pitfalls + +1. **Shared key mismatch** -- The pre-shared key must match exactly on both the Azure connection and the on-premises VPN device. Even trailing whitespace causes the tunnel to fail. +2. **Connection type cannot be changed** -- Once created, the connection type (IPsec, Vnet2Vnet, ExpressRoute) is immutable. Delete and recreate to change. +3. **Gateway SKU limits connections** -- Basic VPN gateway supports only 10 S2S tunnels. VpnGw1 supports 30. Check SKU limits before adding connections. +4. **IKE version mismatch** -- If the on-premises device only supports IKEv1, set `connectionProtocol` to `IKEv1`. The default IKEv2 causes negotiation failures with older devices. +5. **Policy-based vs route-based** -- Policy-based traffic selectors (`usePolicyBasedTrafficSelectors: true`) are needed for some on-premises devices but limit you to a single tunnel and no BGP. +6. **Shared key in state file** -- The `sharedKey` is stored in plain text in Terraform state. Use a remote backend with encryption, or reference Key Vault secrets. +7. **BGP requires compatible ASNs** -- When `enableBgp: true`, both the Azure VPN gateway and on-premises device must be configured with non-conflicting ASNs. + +## Production Backlog Items + +- [ ] Configure custom IPsec/IKE policy for compliance (AES256, SHA256, DH Group 14+) +- [ ] Enable BGP for dynamic route propagation +- [ ] Set up active-active VPN gateway for high availability +- [ ] Implement connection monitoring and alerts via Network Watcher +- [ ] Add redundant connections to secondary on-premises VPN device +- [ ] Store pre-shared key in Key Vault with rotation policy +- [ ] Configure DPD (Dead Peer Detection) timeout appropriate for the on-premises device +- [ ] Plan ExpressRoute as primary with VPN as backup (coexistence) diff --git a/azext_prototype/knowledge/services/network-interface.md b/azext_prototype/knowledge/services/network-interface.md new file mode 100644 index 0000000..576bae9 --- /dev/null +++ b/azext_prototype/knowledge/services/network-interface.md @@ -0,0 +1,358 @@ +--- +service_namespace: Microsoft.Network/networkInterfaces +display_name: Network Interface +--- + +# Azure Network Interface +> Virtual network interface card (NIC) that connects Azure virtual machines and other compute resources to a virtual network for network communication. + +## When to Use + +- **Virtual machine networking** -- every Azure VM requires at least one NIC for network connectivity +- **Multiple NICs per VM** -- separate management, application, and data traffic on different subnets +- **Network virtual appliances** -- firewalls and routers that need multiple NICs with IP forwarding +- **Custom IP configuration** -- static private IPs, multiple IP configurations, or secondary IPs +- **Accelerated networking** -- high-performance networking for latency-sensitive workloads + +NICs are companion resources -- they are always created alongside VMs or other compute resources. You rarely deploy a NIC standalone; it accompanies a VM, VMSS, or network virtual appliance deployment. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| IP allocation | Dynamic | Static for production servers needing stable IPs | +| Public IP | None | Use Azure Bastion for management access | +| Accelerated networking | Enabled | Supported on most D/E/F/M series VMs | +| DNS servers | Inherited from VNet | Custom DNS only if required | +| NSG | Attached at subnet level | Prefer subnet-level NSG over NIC-level | +| IP forwarding | Disabled | Enable only for NVA/firewall scenarios | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "nic" { + type = "Microsoft.Network/networkInterfaces@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enableAcceleratedNetworking = true # Supported on D2s_v5 and larger + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + primary = true + privateIPAllocationMethod = "Dynamic" # "Static" with privateIPAddress for fixed IP + subnet = { + id = var.subnet_id + } + } + } + ] + } + } + + tags = var.tags + + response_export_values = ["properties.ipConfigurations[0].properties.privateIPAddress"] +} +``` + +### With Static IP + +```hcl +resource "azapi_resource" "nic_static" { + type = "Microsoft.Network/networkInterfaces@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enableAcceleratedNetworking = true + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + primary = true + privateIPAllocationMethod = "Static" + privateIPAddress = var.private_ip_address + subnet = { + id = var.subnet_id + } + } + } + ] + } + } + + tags = var.tags +} +``` + +### With Public IP (not recommended for production) + +```hcl +resource "azapi_resource" "public_ip" { + type = "Microsoft.Network/publicIPAddresses@2023-11-01" + name = "pip-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + } + properties = { + publicIPAllocationMethod = "Static" + publicIPAddressVersion = "IPv4" + } + } + + tags = var.tags +} + +resource "azapi_resource" "nic_public" { + type = "Microsoft.Network/networkInterfaces@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enableAcceleratedNetworking = true + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + primary = true + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + publicIPAddress = { + id = azapi_resource.public_ip.id + } + } + } + ] + } + } + + tags = var.tags +} +``` + +### Multiple IP Configurations + +```hcl +resource "azapi_resource" "nic_multi_ip" { + type = "Microsoft.Network/networkInterfaces@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enableAcceleratedNetworking = true + ipConfigurations = [ + { + name = "ipconfig-primary" + properties = { + primary = true + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + } + }, + { + name = "ipconfig-secondary" + properties = { + primary = false + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + } + } + ] + } + } + + tags = var.tags +} +``` + +### With NSG Attachment + +```hcl +resource "azapi_resource" "nic_with_nsg" { + type = "Microsoft.Network/networkInterfaces@2023-11-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + enableAcceleratedNetworking = true + networkSecurityGroup = { + id = var.nsg_id + } + ipConfigurations = [ + { + name = "ipconfig1" + properties = { + primary = true + privateIPAllocationMethod = "Dynamic" + subnet = { + id = var.subnet_id + } + } + } + ] + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# NICs are typically managed through resource group-level RBAC. +# Network Contributor role on the resource group or subscription scope. +resource "azapi_resource" "network_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.resource_group_id}${var.admin_principal_id}network-contributor") + parent_id = var.resource_group_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.admin_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +NICs do not support private endpoints -- they are themselves the network interface for VMs and other resources. Private endpoints create their own managed NICs automatically. + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the network interface') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Subnet ID') +param subnetId string + +@description('Enable accelerated networking') +param enableAcceleratedNetworking bool = true + +@description('Tags to apply') +param tags object = {} + +resource nic 'Microsoft.Network/networkInterfaces@2023-11-01' = { + name: name + location: location + tags: tags + properties: { + enableAcceleratedNetworking: enableAcceleratedNetworking + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + primary: true + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: subnetId + } + } + } + ] + } +} + +output id string = nic.id +output name string = nic.name +output privateIPAddress string = nic.properties.ipConfigurations[0].properties.privateIPAddress +``` + +### With Load Balancer Backend Pool + +```bicep +@description('Load balancer backend pool ID') +param lbBackendPoolId string = '' + +resource nic 'Microsoft.Network/networkInterfaces@2023-11-01' = { + name: name + location: location + tags: tags + properties: { + enableAcceleratedNetworking: true + ipConfigurations: [ + { + name: 'ipconfig1' + properties: { + primary: true + privateIPAllocationMethod: 'Dynamic' + subnet: { + id: subnetId + } + loadBalancerBackendAddressPools: !empty(lbBackendPoolId) ? [ + { + id: lbBackendPoolId + } + ] : [] + } + } + ] + } +} +``` + +### RBAC Assignment + +NICs inherit RBAC from the resource group. Use Network Contributor role at the resource group scope for NIC management. + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Accelerated networking on unsupported VM size | NIC creation or VM attachment fails | Check VM size supports accelerated networking before enabling | +| NIC-level and subnet-level NSG conflict | Unexpected traffic blocking from dual evaluation | Prefer subnet-level NSGs; use NIC-level only when per-VM rules are needed | +| Static IP outside subnet range | NIC creation fails | Verify the static IP falls within the subnet address space | +| Deleting NIC attached to VM | Deletion fails with dependency error | Detach NIC from VM or delete VM first | +| IP forwarding disabled on NVA | NVA cannot route traffic between subnets | Enable `enableIPForwarding = true` for firewall/router NICs | +| Public IP on production VMs | Direct internet exposure; security risk | Use Azure Bastion, VPN, or Load Balancer instead of public IPs | +| Subnet full | NIC creation fails with no available IPs | Monitor subnet IP utilization; plan subnet sizing for growth | +| DNS server misconfiguration | VM cannot resolve hostnames | Inherit VNet DNS settings unless custom DNS is explicitly required | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Remove public IPs | P1 | Migrate to Azure Bastion for management access; remove public IPs | +| NSG hardening | P1 | Review and restrict NSG rules to minimum required traffic | +| Static IPs for servers | P2 | Assign static private IPs to servers that need stable addresses | +| Accelerated networking | P2 | Verify and enable accelerated networking on all supported VMs | +| Application security groups | P2 | Use ASGs for logical grouping and simplified NSG rules | +| DNS configuration | P3 | Configure custom DNS servers if using private DNS zones | +| Network monitoring | P2 | Enable NSG flow logs and Traffic Analytics | +| IP address planning | P3 | Document and plan IP address allocation across subnets | +| Multiple NICs for NVAs | P3 | Configure multi-NIC setups for network virtual appliance deployments | +| Diagnostic logging | P3 | Enable NIC diagnostic settings for network troubleshooting | diff --git a/azext_prototype/knowledge/services/network-security-group.md b/azext_prototype/knowledge/services/network-security-group.md new file mode 100644 index 0000000..5c15407 --- /dev/null +++ b/azext_prototype/knowledge/services/network-security-group.md @@ -0,0 +1,125 @@ +--- +service_namespace: Microsoft.Network/networkSecurityGroups +display_name: Network Security Group +depends_on: [] +--- + +# Network Security Group + +> Stateful packet filter that controls inbound and outbound traffic to Azure resources. Attached to subnets or NICs to enforce network segmentation. + +## When to Use +- Every subnet should have an NSG attached for traffic filtering +- Control traffic between subnets (east-west) and to/from the internet (north-south) +- Enforce micro-segmentation between application tiers + +## POC Defaults +- **Default rules**: Allow VNet-to-VNet, deny all inbound from internet +- **Priority**: Start at 100, increment by 10 for readability +- **Diagnostic settings**: NSGs do NOT support diagnostic settings (unlike VNets) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "nsg" { + type = "Microsoft.Network/networkSecurityGroups@2024-01-01" + name = var.nsg_name + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + securityRules = [ + { + name = "DenyAllInbound" + properties = { + priority = 4096 + direction = "Inbound" + access = "Deny" + protocol = "*" + sourcePortRange = "*" + destinationPortRange = "*" + sourceAddressPrefix = "*" + destinationAddressPrefix = "*" + } + } + ] + } + } + + tags = var.tags +} +``` + +### RBAC Assignment +```hcl +# Network Contributor role for NSG management: +# 4d97b98b-1d4f-4787-a291-c67834d212e7 +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param nsgName string +param location string = resourceGroup().location +param tags object = {} + +resource nsg 'Microsoft.Network/networkSecurityGroups@2024-01-01' = { + name: nsgName + location: location + properties: { + securityRules: [ + { + name: 'DenyAllInbound' + properties: { + priority: 4096 + direction: 'Inbound' + access: 'Deny' + protocol: '*' + sourcePortRange: '*' + destinationPortRange: '*' + sourceAddressPrefix: '*' + destinationAddressPrefix: '*' + } + } + ] + } + tags: tags +} + +output nsgId string = nsg.id +output nsgName string = nsg.name +``` + +## Application Code + +### Python +```python +# NSGs are infrastructure — no application code. Traffic filtering +# happens at the network level, transparent to applications. +``` + +### C# +```csharp +// NSGs are infrastructure — no application code. +``` + +### Node.js +```typescript +// NSGs are infrastructure — no application code. +``` + +## Common Pitfalls +- **NSGs do NOT support diagnostic settings**: Unlike VNets, NSGs have no diagnostic categories. Do not create diagnostic settings for NSGs — ARM will reject with HTTP 400. +- **Wildcard source/destination**: Rules with `sourceAddressPrefix = "*"` allow all traffic. Use service tags (VirtualNetwork, AzureLoadBalancer) or specific CIDR ranges. +- **Rule priority conflicts**: Lower priority numbers are evaluated first. Ensure allow rules have lower priority than deny rules. +- **GatewaySubnet NSG restrictions**: NSGs on GatewaySubnet must allow Azure Gateway Manager ports (65200-65535) or VPN/ExpressRoute health probes will fail. +- **Stateful behavior**: NSG rules are stateful — if inbound traffic is allowed, the return traffic is automatically allowed without an explicit outbound rule. + +## Production Backlog Items +- NSG flow logs for traffic analysis and threat detection +- Application Security Groups (ASGs) for role-based network rules +- Network Watcher integration for topology visualization +- Automated NSG rule auditing for compliance diff --git a/azext_prototype/knowledge/services/notification-hub.md b/azext_prototype/knowledge/services/notification-hub.md new file mode 100644 index 0000000..7590be4 --- /dev/null +++ b/azext_prototype/knowledge/services/notification-hub.md @@ -0,0 +1,135 @@ +--- +service_namespace: Microsoft.NotificationHubs/namespaces/notificationHubs +display_name: Notification Hub +depends_on: + - Microsoft.NotificationHubs/namespaces +--- + +# Notification Hub + +> A push notification hub within a Notification Hubs namespace that enables sending push notifications to iOS (APNs), Android (FCM), Windows (WNS), and other platforms at scale. + +## When to Use +- Send push notifications to mobile apps across multiple platforms (iOS, Android, Windows) +- Broadcast notifications to millions of devices with a single API call +- Tag-based routing to send targeted notifications to user segments +- Template notifications for platform-independent message formatting +- NOT suitable for: SMS/email notifications (use Communication Services), real-time messaging (use SignalR) + +## POC Defaults +- **SKU**: Free (500 active devices, 1M pushes/month — inherited from namespace) +- **APNs**: Token-based auth (simpler than certificate-based for POC) +- **FCM**: FCM v1 API key +- **Registration TTL**: 90 days + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "notification_hub" { + type = "Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview" + name = var.hub_name + parent_id = azapi_resource.nh_namespace.id + location = var.location + + body = { + properties = { + name = var.hub_name + } + } +} +``` + +### RBAC Assignment +```hcl +# Notification Hubs use Shared Access Policies (SAS), not Azure RBAC. +# DefaultFullSharedAccessSignature is created automatically. +# For least-privilege, create custom policies: +# - Listen: mobile clients for registration +# - Send: backend services for pushing +# - Manage: admin operations +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param hubName string +param location string + +resource hub 'Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview' = { + parent: nhNamespace + name: hubName + location: location + properties: { + name: hubName + } +} + +output hubName string = hub.name +``` + +## Application Code + +### Python +```python +from azure.notificationhubs import NotificationHubClient + +hub_client = NotificationHubClient(connection_string, hub_name) + +# Send a template notification (platform-independent) +hub_client.send_notification( + notification={"message": "Hello from Azure!"}, + tags="user:12345" +) + +# Send platform-specific (FCM) +hub_client.send_gcm_native_notification( + '{"data": {"message": "Hello Android!"}}', + tags="platform:android" +) +``` + +### C# +```csharp +using Microsoft.Azure.NotificationHubs; + +var hub = NotificationHubClient.CreateClientFromConnectionString(connectionString, hubName); + +// Template notification (cross-platform) +await hub.SendTemplateNotificationAsync( + new Dictionary { { "message", "Hello from Azure!" } }, + "user:12345"); + +// FCM native notification +await hub.SendFcmV1NativeNotificationAsync( + """{"message":{"notification":{"title":"Hello","body":"World"}}}""", + "platform:android"); +``` + +### Node.js +```typescript +import { NotificationHubsClient } from "@azure/notification-hubs"; + +const client = new NotificationHubsClient(connectionString, hubName); + +// Send a template notification +await client.sendNotification({ + body: JSON.stringify({ message: "Hello from Azure!" }), + headers: { "ServiceBusNotification-Tags": "user:12345" }, +}); +``` + +## Common Pitfalls +- **Platform credentials required**: The hub itself is just a container. You must configure APNs/FCM/WNS credentials before any notifications can be sent. Missing credentials fail silently. +- **Free tier limits**: Free SKU supports 500 active devices and 1M pushes/month. Exceeding these limits drops notifications without error. +- **SAS, not RBAC**: Notification Hubs use Shared Access Signature authentication, not Azure RBAC. Connection strings contain the SAS key. +- **FCM v1 migration**: Google deprecated the legacy FCM API. Use FCM v1 API credentials (service account JSON), not the legacy server key. +- **Registration staleness**: Device registrations expire. Clients must re-register on app startup to keep registrations fresh. + +## Production Backlog Items +- Platform credential configuration (APNs token, FCM v1 service account, WNS client secret) +- Tag-based audience segmentation strategy +- Template registration for cross-platform notifications +- Push notification analytics and delivery tracking +- Upgrade to Standard SKU for higher device limits and telemetry diff --git a/azext_prototype/knowledge/services/notification-hubs.md b/azext_prototype/knowledge/services/notification-hubs.md new file mode 100644 index 0000000..bc14282 --- /dev/null +++ b/azext_prototype/knowledge/services/notification-hubs.md @@ -0,0 +1,206 @@ +--- +service_namespace: Microsoft.NotificationHubs/namespaces +display_name: Azure Notification Hubs +--- + +# Azure Notification Hubs +> Scalable push notification engine for sending personalized notifications to mobile and web applications across all major platforms (iOS, Android, Windows, Web Push). + +## When to Use + +- **Mobile push notifications** -- send notifications to iOS (APNs), Android (FCM), Windows (WNS) devices +- **Web push** -- browser-based push notifications via Web Push protocol +- **Broadcast messaging** -- send to millions of devices simultaneously with low latency +- **Personalized notifications** -- tag-based routing for user segmentation and targeting +- **Cross-platform** -- single API to reach all platforms without managing platform-specific integrations + +Choose Notification Hubs over direct platform integration (APNs/FCM) when you need cross-platform abstraction, tag-based routing, or scale beyond individual platform limits. Choose direct platform SDKs for simple single-platform apps with minimal notification needs. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Free | 1M pushes, 500 active devices; sufficient for POC | +| Namespace SKU | Free | Namespace contains one or more hubs | +| Platforms | Configure as needed | APNs (iOS), FCM (Android), WNS (Windows) | +| Authentication | Managed identity for backend | SAS tokens for direct device registration | +| Tags | Enabled | Use tags for user/group targeting | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "notification_namespace" { + type = "Microsoft.NotificationHubs/namespaces@2023-10-01-preview" + name = var.namespace_name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Free" # Free for POC; Basic or Standard for production + } + properties = { + namespaceType = "NotificationHub" + } + } + + tags = var.tags +} + +resource "azapi_resource" "notification_hub" { + type = "Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview" + name = var.hub_name + location = var.location + parent_id = azapi_resource.notification_namespace.id + + body = { + properties = {} + } + + tags = var.tags +} +``` + +### Platform Configuration (FCM v1) + +```hcl +resource "azapi_update_resource" "fcm_credential" { + type = "Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview" + resource_id = azapi_resource.notification_hub.id + + body = { + properties = { + gcmCredential = { + properties = { + googleApiKey = var.fcm_server_key # Store in Key Vault + gcmEndpoint = "https://fcm.googleapis.com/fcm/send" + } + } + } + } +} +``` + +### Platform Configuration (APNs) + +```hcl +resource "azapi_update_resource" "apns_credential" { + type = "Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview" + resource_id = azapi_resource.notification_hub.id + + body = { + properties = { + apnsCredential = { + properties = { + apnsCertificate = var.apns_certificate # Base64 .p12 certificate + certificateKey = var.apns_certificate_key + endpoint = "https://api.sandbox.push.apple.com:443/3/device" # Use api.push.apple.com for production + } + } + } + } +} +``` + +### RBAC Assignment + +```hcl +# Notification Hubs does not have dedicated data-plane RBAC roles. +# Use Contributor or custom roles for management-plane access. +# SAS tokens (DefaultFullSharedAccessSignature, DefaultListenSharedAccessSignature) +# are used for data-plane operations (sending, registering). + +resource "azapi_resource" "nh_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.notification_namespace.id}${var.managed_identity_principal_id}contributor") + parent_id = azapi_resource.notification_namespace.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = var.managed_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### Private Endpoint + +Notification Hubs does not support private endpoints. All communication is over HTTPS. Secure access using SAS tokens with appropriate permissions (Listen for devices, Send for backend). + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the Notification Hubs namespace') +param namespaceName string + +@description('Name of the notification hub') +param hubName string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Tags to apply') +param tags object = {} + +resource notificationNamespace 'Microsoft.NotificationHubs/namespaces@2023-10-01-preview' = { + name: namespaceName + location: location + tags: tags + sku: { + name: 'Free' + } + properties: { + namespaceType: 'NotificationHub' + } +} + +resource notificationHub 'Microsoft.NotificationHubs/namespaces/notificationHubs@2023-10-01-preview' = { + parent: notificationNamespace + name: hubName + location: location + tags: tags + properties: {} +} + +output namespaceId string = notificationNamespace.id +output hubId string = notificationHub.id +output hubName string = notificationHub.name +``` + +### RBAC Assignment + +Notification Hubs uses SAS-based authentication for data-plane operations. Use ARM RBAC (Contributor) for management-plane access only. + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| Free tier limits | 500 active devices, 1M pushes; quickly exhausted | Monitor usage; upgrade to Basic for production testing | +| APNs sandbox vs production endpoint | Notifications fail in production or development | Use sandbox endpoint for dev, production endpoint for release builds | +| FCM legacy API deprecation | Google deprecated legacy FCM HTTP API | Use FCM v1 API (HTTP v1) with service account JSON credentials | +| Missing platform credentials | Push silently fails for that platform | Configure all target platform credentials before testing | +| Tag expression complexity | Invalid tag expressions cause send failures | Test tag expressions with small audiences first; max 20 tags per expression | +| Registration expiration | Stale registrations waste quota | Implement registration refresh on app launch; use installation API | +| Large payload size | Platform-specific size limits cause truncation | APNs: 4 KB, FCM: 4 KB, WNS: 5 KB -- keep payloads small | +| SAS token management | Leaked tokens allow unauthorized sends | Rotate SAS keys regularly; use Listen-only tokens on devices | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| Upgrade to Basic/Standard SKU | P1 | Remove device limits and enable telemetry | +| FCM v1 migration | P1 | Migrate from legacy FCM to HTTP v1 API with service account | +| Installation API | P2 | Migrate from registrations to installations API for better device management | +| Telemetry and analytics | P2 | Enable per-message telemetry for delivery tracking (Standard tier) | +| Scheduled sends | P3 | Configure scheduled notifications for time-zone-aware delivery | +| Template registrations | P2 | Use templates for cross-platform notification formatting | +| Tag management | P2 | Implement user segmentation strategy with tags | +| Certificate rotation | P1 | Automate APNs certificate rotation before expiry | +| Monitoring and alerts | P2 | Set up alerts for push failures, throttling, and quota usage | +| Multi-hub architecture | P3 | Separate hubs per environment (dev/staging/prod) for isolation | diff --git a/azext_prototype/knowledge/services/operations-management-solution.md b/azext_prototype/knowledge/services/operations-management-solution.md new file mode 100644 index 0000000..9e9964b --- /dev/null +++ b/azext_prototype/knowledge/services/operations-management-solution.md @@ -0,0 +1,156 @@ +--- +service_namespace: Microsoft.OperationsManagement/solutions +display_name: Operations Management Solution +--- + +# Operations Management Solution + +> Gallery solution deployed on a Log Analytics workspace that adds specialized monitoring capabilities such as Microsoft Sentinel, Change Tracking, Update Management, or Container Insights. + +## When to Use +- **Enable Microsoft Sentinel** -- deploy `SecurityInsights` solution to activate SIEM/SOAR on a workspace +- **Container Insights** -- deploy `ContainerInsights` for AKS monitoring dashboards and log collection +- **Change Tracking** -- deploy `ChangeTracking` for tracking configuration changes on VMs +- **Update Management** -- deploy `Updates` for OS patch compliance tracking +- **Service Map** -- deploy `ServiceMap` for application dependency mapping +- **VM Insights** -- deploy `VMInsights` for VM performance monitoring + +Solutions extend Log Analytics with pre-built views, saved queries, and dashboards for specific scenarios. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Publisher | Microsoft | All first-party solutions | +| Plan product | OMSGallery/ | Naming convention for gallery solutions | +| Name format | `()` | Must follow this exact format | + +## Terraform Patterns + +### Basic Resource + +```hcl +# Microsoft Sentinel solution +resource "azapi_resource" "sentinel_solution" { + type = "Microsoft.OperationsManagement/solutions@2015-11-01-preview" + name = "SecurityInsights(${var.workspace_name})" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + workspaceResourceId = var.workspace_id + } + plan = { + name = "SecurityInsights(${var.workspace_name})" + publisher = "Microsoft" + product = "OMSGallery/SecurityInsights" + } + } + + tags = var.tags +} + +# Container Insights solution +resource "azapi_resource" "container_insights" { + type = "Microsoft.OperationsManagement/solutions@2015-11-01-preview" + name = "ContainerInsights(${var.workspace_name})" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + workspaceResourceId = var.workspace_id + } + plan = { + name = "ContainerInsights(${var.workspace_name})" + publisher = "Microsoft" + product = "OMSGallery/ContainerInsights" + } + } + + tags = var.tags +} +``` + +### RBAC Assignment + +```hcl +# Log Analytics Contributor on the workspace for solution management +resource "azapi_resource" "la_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.workspace_id}-${var.principal_id}-la-contributor") + parent_id = var.workspace_id + + body = { + properties = { + roleDefinitionId = "/providers/Microsoft.Authorization/roleDefinitions/92aaf0da-9dab-42b6-94a3-d43ce8d16293" + principalId = var.principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Log Analytics workspace name') +param workspaceName string + +@description('Log Analytics workspace resource ID') +param workspaceId string + +@description('Azure region') +param location string = resourceGroup().location + +param tags object = {} + +resource sentinelSolution 'Microsoft.OperationsManagement/solutions@2015-11-01-preview' = { + name: 'SecurityInsights(${workspaceName})' + location: location + tags: tags + properties: { + workspaceResourceId: workspaceId + } + plan: { + name: 'SecurityInsights(${workspaceName})' + publisher: 'Microsoft' + product: 'OMSGallery/SecurityInsights' + } +} + +output id string = sentinelSolution.id +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Solutions add monitoring capabilities to the workspace; applications send telemetry through standard diagnostic settings and SDKs. + +### C# +Infrastructure -- transparent to application code. Solutions add monitoring capabilities to the workspace; applications send telemetry through standard diagnostic settings and SDKs. + +### Node.js +Infrastructure -- transparent to application code. Solutions add monitoring capabilities to the workspace; applications send telemetry through standard diagnostic settings and SDKs. + +## Common Pitfalls + +1. **Name format must be exact** -- The name must follow `()` exactly. Deviations cause deployment failures or orphaned resources. +2. **Plan name must match resource name** -- The `plan.name` and resource `name` must be identical. Mismatches cause cryptic ARM errors. +3. **API version is old but stable** -- The `2015-11-01-preview` API is the only available version. Despite being a preview API from 2015, it is the production API for solutions. +4. **Location must match workspace** -- The solution location must match the Log Analytics workspace location. Cross-region deployment fails. +5. **Duplicate solutions** -- Deploying the same solution type twice on a workspace creates conflicts. Check for existing solutions before deploying. +6. **Deletion removes data views, not data** -- Removing a solution removes its dashboards and saved queries but does not delete the underlying log data in the workspace. +7. **Some solutions are deprecated** -- Microsoft is migrating from OMS solutions to newer patterns (DCR-based monitoring, Sentinel content hub). Check whether a newer alternative exists. + +## Production Backlog Items + +- [ ] Audit deployed solutions and remove unused ones to reduce complexity +- [ ] Migrate from legacy solutions to DCR-based monitoring where available +- [ ] Implement Sentinel content hub solutions instead of manual OMS solution deployment +- [ ] Configure solution-specific settings (e.g., Container Insights data collection rules) +- [ ] Set up alerts for solution health and data freshness +- [ ] Document which solutions are deployed per workspace for operations team diff --git a/azext_prototype/knowledge/services/postgresql-flexible-administrator.md b/azext_prototype/knowledge/services/postgresql-flexible-administrator.md new file mode 100644 index 0000000..a48462f --- /dev/null +++ b/azext_prototype/knowledge/services/postgresql-flexible-administrator.md @@ -0,0 +1,133 @@ +--- +service_namespace: Microsoft.DBforPostgreSQL/flexibleServers/administrators +display_name: PostgreSQL Flexible Server Administrator +depends_on: + - Microsoft.DBforPostgreSQL/flexibleServers +--- + +# PostgreSQL Flexible Server Administrator + +> Configures Microsoft Entra ID (Azure AD) authentication administrators on a PostgreSQL Flexible Server, enabling passwordless managed identity access. + +## When to Use +- Enable Entra ID authentication for passwordless connections from Azure services +- Assign a managed identity or user principal as the PostgreSQL server administrator +- Required before any Entra ID token-based connections can be established +- Use alongside (or instead of) local PostgreSQL password authentication + +## POC Defaults +- **Principal type**: ServicePrincipal (for managed identity) or User (for dev access) +- **Auth type**: ActiveDirectory +- **Entra-only auth**: Disabled (allows both Entra and password auth for POC flexibility) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "pg_ad_admin" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/administrators@2023-06-01-preview" + name = var.deployer_object_id + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + principalName = var.admin_principal_name + principalType = "ServicePrincipal" + tenantId = var.tenant_id + } + } +} +``` + +### RBAC Assignment +```hcl +# The administrator identity is set at the PostgreSQL level, not via Azure RBAC. +# The principalName must match the display name of the Entra identity. +# After deployment, the Entra admin can create additional PostgreSQL roles: +# SELECT * FROM pgaadauth_create_principal('', false, false); +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param principalName string +param principalObjectId string +param tenantId string = tenant().tenantId + +resource pgAdmin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2023-06-01-preview' = { + parent: pgServer + name: principalObjectId + properties: { + principalName: principalName + principalType: 'ServicePrincipal' + tenantId: tenantId + } +} +``` + +## Application Code + +### Python +```python +from azure.identity import DefaultAzureCredential +import psycopg2 + +# Once an Entra admin is configured, managed identities can authenticate +credential = DefaultAzureCredential() +token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") + +conn = psycopg2.connect( + host=".postgres.database.azure.com", + dbname="mydb", + user="", + password=token.token, + sslmode="require" +) +``` + +### C# +```csharp +using Azure.Identity; +using Npgsql; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://ossrdbms-aad.database.windows.net/.default" })); + +var connStr = $"Host=.postgres.database.azure.com;Database=mydb;Username=;Password={token.Token};SSL Mode=Require"; +await using var conn = new NpgsqlConnection(connStr); +await conn.OpenAsync(); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { Client } from "pg"; + +const credential = new DefaultAzureCredential(); +const token = await credential.getToken("https://ossrdbms-aad.database.windows.net/.default"); + +const client = new Client({ + host: ".postgres.database.azure.com", + database: "mydb", + user: "", + password: token.token, + ssl: { rejectUnauthorized: true }, + port: 5432, +}); +await client.connect(); +``` + +## Common Pitfalls +- **Name must be the object ID**: The resource name for the administrator must be the Entra object ID of the principal, not a friendly name. +- **pgaadauth extension required**: The `azure.extensions` server parameter must include `pgaadauth` for Entra authentication to work. Ensure the server configuration enables it. +- **Principal name must match exactly**: The `principalName` must match the exact display name of the managed identity or user in Entra ID. +- **Only one Entra admin at a time**: PostgreSQL Flexible Server supports one Entra administrator. Setting a new one replaces the previous. +- **Token scope differs from SQL**: Use `https://ossrdbms-aad.database.windows.net/.default`, not `https://database.windows.net/.default`. + +## Production Backlog Items +- Enable Entra-only authentication (disable password auth) +- Rotate administrator principal on identity lifecycle changes +- Audit Entra admin actions via PostgreSQL audit logging +- Configure additional PostgreSQL roles via pgaadauth_create_principal diff --git a/azext_prototype/knowledge/services/postgresql-flexible-configuration.md b/azext_prototype/knowledge/services/postgresql-flexible-configuration.md new file mode 100644 index 0000000..e99b832 --- /dev/null +++ b/azext_prototype/knowledge/services/postgresql-flexible-configuration.md @@ -0,0 +1,107 @@ +--- +service_namespace: Microsoft.DBforPostgreSQL/flexibleServers/configurations +display_name: PostgreSQL Flexible Server Configuration +depends_on: + - Microsoft.DBforPostgreSQL/flexibleServers +--- + +# PostgreSQL Flexible Server Configuration + +> Server-level parameters that control PostgreSQL engine behavior, extensions, and performance tuning on Azure Database for PostgreSQL Flexible Server. + +## When to Use +- Enable PostgreSQL extensions (pgvector, PostGIS, pg_stat_statements, pgaadauth) +- Tune performance parameters (shared_buffers, work_mem, max_connections) +- Configure logging and auditing settings +- Enable connection pooling (PgBouncer) at the server level +- Required to enable `azure.extensions` before using any non-default extensions + +## POC Defaults +- **azure.extensions**: pgcrypto,uuid-ossp (add pgvector for AI workloads, pgaadauth for Entra auth) +- **pgbouncer.enabled**: false (enable for connection pooling) +- **log_checkpoints**: on +- **log_connections**: on + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "pg_config_extensions" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-06-01-preview" + name = "azure.extensions" + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + value = "pgcrypto,uuid-ossp,pgaadauth" + source = "user-override" + } + } +} + +resource "azapi_resource" "pg_config_pgbouncer" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-06-01-preview" + name = "pgbouncer.enabled" + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + value = "true" + source = "user-override" + } + } +} +``` + +### RBAC Assignment +```hcl +# Configuration changes require Contributor or Owner on the Flexible Server resource. +# No separate RBAC role exists for configuration management. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource extensionsConfig 'Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-06-01-preview' = { + parent: pgServer + name: 'azure.extensions' + properties: { + value: 'pgcrypto,uuid-ossp,pgaadauth' + source: 'user-override' + } +} + +resource pgbouncerConfig 'Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-06-01-preview' = { + parent: pgServer + name: 'pgbouncer.enabled' + properties: { + value: 'true' + source: 'user-override' + } +} +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **Server restart required**: Some parameters (like `shared_preload_libraries`) require a server restart to take effect. The deployment may appear successful but changes won't apply until restart. +- **Extension allowlist first**: You must add extensions to `azure.extensions` before you can `CREATE EXTENSION` in SQL. Forgetting this step produces `extension not available` errors. +- **PgBouncer port differs**: When PgBouncer is enabled, applications connect on port 6432 (not 5432). Using the wrong port causes connection failures. +- **Dependent configurations**: Some parameters depend on others (e.g., `pgbouncer.default_pool_size` only works when `pgbouncer.enabled` is true). +- **Read-only parameters**: Some parameters (like `max_connections`) are read-only on certain SKUs — the API accepts the change but it has no effect. + +## Production Backlog Items +- Performance tuning based on workload profiling (shared_buffers, work_mem, effective_cache_size) +- Enable pg_stat_statements for query performance monitoring +- Configure audit logging via pgaudit extension +- SSL enforcement and minimum TLS version configuration diff --git a/azext_prototype/knowledge/services/postgresql-flexible-database.md b/azext_prototype/knowledge/services/postgresql-flexible-database.md new file mode 100644 index 0000000..7d4d0f7 --- /dev/null +++ b/azext_prototype/knowledge/services/postgresql-flexible-database.md @@ -0,0 +1,136 @@ +--- +service_namespace: Microsoft.DBforPostgreSQL/flexibleServers/databases +display_name: PostgreSQL Flexible Server Database +depends_on: + - Microsoft.DBforPostgreSQL/flexibleServers +--- + +# PostgreSQL Flexible Server Database + +> A database within a PostgreSQL Flexible Server instance. + +## When to Use +- Every PostgreSQL application needs at least one database +- Use separate databases for different application domains or tenants +- Default databases (postgres, azure_maintenance) should not be used for application data + +## POC Defaults +- **Charset**: UTF8 +- **Collation**: en_US.utf8 + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "pg_database" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/databases@2023-06-01-preview" + name = var.database_name + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + charset = "UTF8" + collation = "en_US.utf8" + } + } +} +``` + +### RBAC Assignment +```hcl +# PostgreSQL database access uses PostgreSQL-native roles, not Azure RBAC. +# After deployment, connect as the Entra admin and run: +# CREATE ROLE LOGIN; +# GRANT ALL ON DATABASE TO ; +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param databaseName string + +resource database 'Microsoft.DBforPostgreSQL/flexibleServers/databases@2023-06-01-preview' = { + parent: pgServer + name: databaseName + properties: { + charset: 'UTF8' + collation: 'en_US.utf8' + } +} + +output databaseName string = database.name +``` + +## Application Code + +### Python +```python +import psycopg2 +from azure.identity import DefaultAzureCredential + +credential = DefaultAzureCredential() +token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") + +conn = psycopg2.connect( + host=".postgres.database.azure.com", + dbname=database_name, + user="", + password=token.token, + sslmode="require" +) +cursor = conn.cursor() +cursor.execute("SELECT version()") +print(cursor.fetchone()) +conn.close() +``` + +### C# +```csharp +using Azure.Identity; +using Npgsql; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://ossrdbms-aad.database.windows.net/.default" })); + +var connectionString = $"Host=.postgres.database.azure.com;Database={databaseName};Username=;Password={token.Token};SSL Mode=Require"; + +await using var conn = new NpgsqlConnection(connectionString); +await conn.OpenAsync(); +await using var cmd = new NpgsqlCommand("SELECT version()", conn); +Console.WriteLine(await cmd.ExecuteScalarAsync()); +``` + +### Node.js +```typescript +import { DefaultAzureCredential } from "@azure/identity"; +import { Client } from "pg"; + +const credential = new DefaultAzureCredential(); +const token = await credential.getToken("https://ossrdbms-aad.database.windows.net/.default"); + +const client = new Client({ + host: ".postgres.database.azure.com", + database: databaseName, + user: "", + password: token.token, + ssl: { rejectUnauthorized: true }, + port: 5432, +}); +await client.connect(); +const res = await client.query("SELECT version()"); +console.log(res.rows[0]); +await client.end(); +``` + +## Common Pitfalls +- **Token scope differs from SQL**: PostgreSQL uses `https://ossrdbms-aad.database.windows.net/.default`, not `https://database.windows.net/.default`. +- **Role creation required**: Like Azure SQL, database-level access requires native PostgreSQL role creation via SQL commands after deployment. +- **Default databases**: Don't use the `postgres` or `azure_maintenance` databases for application data. + +## Production Backlog Items +- Connection pooling via PgBouncer (built into Flexible Server) +- Automated backup and point-in-time restore +- Read replicas for read-heavy workloads +- Schema migration automation diff --git a/azext_prototype/knowledge/services/postgresql-flexible-firewall-rule.md b/azext_prototype/knowledge/services/postgresql-flexible-firewall-rule.md new file mode 100644 index 0000000..b3f74c8 --- /dev/null +++ b/azext_prototype/knowledge/services/postgresql-flexible-firewall-rule.md @@ -0,0 +1,103 @@ +--- +service_namespace: Microsoft.DBforPostgreSQL/flexibleServers/firewallRules +display_name: PostgreSQL Flexible Server Firewall Rule +depends_on: + - Microsoft.DBforPostgreSQL/flexibleServers +--- + +# PostgreSQL Flexible Server Firewall Rule + +> Controls which IP addresses can connect to a PostgreSQL Flexible Server over its public endpoint. Required for non-VNet-integrated servers. + +## When to Use +- Allow Azure services to connect via the special 0.0.0.0 rule +- Allow specific developer IPs for administrative access during POC +- Not needed when server uses VNet integration (private access mode) +- Complement private endpoint connectivity with selective public access + +## POC Defaults +- **AllowAzureServices**: 0.0.0.0 to 0.0.0.0 (enables managed identity access from Azure services) +- **Developer IP rules**: Added as needed for local development + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "pg_firewall_allow_azure" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-06-01-preview" + name = "AllowAzureServices" + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + startIpAddress = "0.0.0.0" + endIpAddress = "0.0.0.0" + } + } +} + +resource "azapi_resource" "pg_firewall_dev" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-06-01-preview" + name = "AllowDevIP" + parent_id = azapi_resource.pg_server.id + + body = { + properties = { + startIpAddress = var.dev_ip + endIpAddress = var.dev_ip + } + } +} +``` + +### RBAC Assignment +```hcl +# Firewall rule management requires Contributor role on the parent Flexible Server. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource firewallAllowAzure 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-06-01-preview' = { + parent: pgServer + name: 'AllowAzureServices' + properties: { + startIpAddress: '0.0.0.0' + endIpAddress: '0.0.0.0' + } +} + +resource firewallDevIp 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-06-01-preview' = { + parent: pgServer + name: 'AllowDevIP' + properties: { + startIpAddress: devIpAddress + endIpAddress: devIpAddress + } +} +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **0.0.0.0 allows ALL Azure services**: This rule allows any Azure service in any subscription, not just yours. Use VNet integration or private endpoints for production. +- **Public access must be enabled**: Firewall rules only work when the server is in public access mode. VNet-integrated servers ignore firewall rules entirely. +- **IP ranges, not CIDR**: PostgreSQL Flexible Server firewall rules use start/end IP addresses, not CIDR notation. +- **No DNS names**: Firewall rules only accept IP addresses, not FQDNs or DNS names. +- **Rule propagation delay**: Firewall rule changes can take up to 5 minutes to propagate. + +## Production Backlog Items +- Remove 0.0.0.0 rule and switch to VNet integration or private endpoints +- Implement IP range restrictions for administrative access via VPN +- Automate firewall rule lifecycle tied to developer onboarding/offboarding +- Monitor and audit firewall rule changes diff --git a/azext_prototype/knowledge/services/postgresql-flexible.md b/azext_prototype/knowledge/services/postgresql-flexible.md new file mode 100644 index 0000000..5479f8c --- /dev/null +++ b/azext_prototype/knowledge/services/postgresql-flexible.md @@ -0,0 +1,564 @@ +--- +service_namespace: Microsoft.DBforPostgreSQL/flexibleServers +display_name: Azure PostgreSQL Flexible Server +--- + +# Azure Database for PostgreSQL - Flexible Server +> Fully managed PostgreSQL database service with zone-resilient high availability, intelligent performance tuning, and fine-grained control over server configuration and maintenance windows. + +## When to Use + +- **Relational data with PostgreSQL** -- teams with PostgreSQL expertise or existing PostgreSQL applications +- **Open-source ecosystem** -- leverage PostgreSQL extensions (PostGIS, pg_trgm, pgvector, TimescaleDB, etc.) +- **Vector search with pgvector** -- lightweight RAG scenarios without a separate vector database +- **Zone-resilient HA** -- built-in zone-redundant or same-zone HA with automatic failover +- **Custom maintenance windows** -- control when patching happens to minimize impact +- **Cost-optimized development** -- burstable tier with stop/start capability for non-production + +Flexible Server is the recommended PostgreSQL service on Azure. It replaces Single Server (deprecated). Choose Flexible Server over Azure SQL when the team prefers PostgreSQL, needs specific extensions, or has existing PostgreSQL tooling. Choose Azure SQL for .NET-heavy stacks or SQL Server feature parity (temporal tables, columnstore). + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Burstable B1ms | 1 vCore, 2 GiB RAM; lowest cost for POC | +| Storage | 32 GiB (P4) | Minimum; auto-grow enabled | +| PostgreSQL version | 16 | Latest stable | +| High availability | Disabled | Zone-redundant HA not needed for POC | +| Backup retention | 7 days | Default; sufficient for POC | +| Geo-redundant backup | Disabled | Enable for production DR | +| Authentication | Azure AD + password | AAD for applications, password for admin bootstrap | +| Public network access | Disabled (unless user overrides) | Use VNet integration or private endpoint | +| PgBouncer | Enabled | Built-in connection pooling | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "pg_flexible" { + type = "Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard_B1ms" + tier = "Burstable" + } + properties = { + version = "16" + administratorLogin = var.admin_username + administratorLoginPassword = var.admin_password # Store in Key Vault + storage = { + storageSizeGB = 32 + autoGrow = "Enabled" + } + backup = { + backupRetentionDays = 7 + geoRedundantBackup = "Disabled" + } + highAvailability = { + mode = "Disabled" # "ZoneRedundant" or "SameZone" for production + } + authConfig = { + activeDirectoryAuth = "Enabled" + passwordAuth = "Enabled" # Needed for initial admin; disable later + tenantId = var.tenant_id + } + } + } + + tags = var.tags + + response_export_values = ["properties.fullyQualifiedDomainName"] +} +``` + +### Firewall Rule (Allow Azure Services) + +```hcl +resource "azapi_resource" "firewall_azure_services" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-12-01-preview" + name = "AllowAzureServices" + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + startIpAddress = "0.0.0.0" + endIpAddress = "0.0.0.0" + } + } +} +``` + +### Database + +```hcl +resource "azapi_resource" "database" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/databases@2023-12-01-preview" + name = var.database_name + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + charset = "UTF8" + collation = "en_US.utf8" + } + } +} +``` + +### Server Configuration (PgBouncer & Extensions) + +```hcl +resource "azapi_resource" "pgbouncer_enabled" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-12-01-preview" + name = "pgbouncer.enabled" + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + value = "True" + source = "user-override" + } + } +} + +resource "azapi_resource" "extensions" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-12-01-preview" + name = "azure.extensions" + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + value = "VECTOR,PG_TRGM,POSTGIS" # Comma-separated list of allowed extensions + source = "user-override" + } + } +} +``` + +### AAD Administrator + +```hcl +resource "azapi_resource" "aad_admin" { + type = "Microsoft.DBforPostgreSQL/flexibleServers/administrators@2023-12-01-preview" + name = var.aad_admin_object_id + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + principalName = var.aad_admin_display_name + principalType = "ServicePrincipal" # or "User", "Group" + tenantId = var.tenant_id + } + } +} +``` + +### RBAC Assignment + +PostgreSQL Flexible Server uses **Azure AD authentication** at the database level, not Azure RBAC role assignments on the ARM resource. After deployment, grant database access via SQL: + +```sql +-- Run as AAD admin after server creation +-- Create AAD role for a managed identity +CREATE ROLE "my-app-identity" LOGIN IN ROLE azure_ad_user; + +-- Grant permissions on the application database +GRANT ALL ON DATABASE appdb TO "my-app-identity"; +GRANT ALL ON ALL TABLES IN SCHEMA public TO "my-app-identity"; +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "my-app-identity"; + +-- Read-only role +CREATE ROLE "my-reader-identity" LOGIN IN ROLE azure_ad_user; +GRANT CONNECT ON DATABASE appdb TO "my-reader-identity"; +GRANT USAGE ON SCHEMA public TO "my-reader-identity"; +GRANT SELECT ON ALL TABLES IN SCHEMA public TO "my-reader-identity"; +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "my-reader-identity"; +``` + +ARM-level RBAC (for management operations only): + +```hcl +resource "azapi_resource" "pg_contributor_role" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${azapi_resource.pg_flexible.id}${var.admin_identity_principal_id}contributor") + parent_id = azapi_resource.pg_flexible.id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c" # Contributor + principalId = var.admin_identity_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +### VNet Integration (Delegated Subnet) + +```hcl +resource "azapi_resource" "postgres_subnet" { + type = "Microsoft.Network/virtualNetworks/subnets@2023-11-01" + name = "snet-postgres" + parent_id = var.vnet_id + + body = { + properties = { + addressPrefix = var.postgres_subnet_cidr + delegations = [ + { + name = "postgresql" + properties = { + serviceName = "Microsoft.DBforPostgreSQL/flexibleServers" + } + } + ] + } + } +} + +resource "azapi_resource" "postgres_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = "${var.name}.private.postgres.database.azure.com" + location = "global" + parent_id = var.resource_group_id + + body = {} +} + +resource "azapi_resource" "postgres_dns_vnet_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = "vnet-link" + location = "global" + parent_id = azapi_resource.postgres_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } +} + +# When using VNet integration, add these to the server properties: +# delegatedSubnetResourceId = azapi_resource.postgres_subnet.id +# privateDnsZoneArmResourceId = azapi_resource.postgres_dns_zone.id +# Note: VNet integration must be set at creation time. +``` + +### Private Endpoint (Alternative to VNet Integration) + +```hcl +resource "azapi_resource" "pg_private_endpoint" { + count = var.enable_private_endpoint && var.subnet_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.name}" + properties = { + privateLinkServiceId = azapi_resource.pg_flexible.id + groupIds = ["postgresqlServer"] + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "pg_pe_dns_zone_group" { + count = var.enable_private_endpoint && var.subnet_id != null && var.private_dns_zone_id != null ? 1 : 0 + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.pg_private_endpoint[0].id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +Private DNS zones: +- VNet integration: `.private.postgres.database.azure.com` +- Private endpoint: `privatelink.postgres.database.azure.com` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the PostgreSQL Flexible Server') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Administrator login') +@secure() +param adminLogin string + +@description('Administrator password') +@secure() +param adminPassword string + +@description('Database name') +param databaseName string = 'appdb' + +@description('Tags to apply') +param tags object = {} + +resource pgServer 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard_B1ms' + tier: 'Burstable' + } + properties: { + version: '16' + administratorLogin: adminLogin + administratorLoginPassword: adminPassword + storage: { + storageSizeGB: 32 + autoGrow: 'Enabled' + } + backup: { + backupRetentionDays: 7 + geoRedundantBackup: 'Disabled' + } + highAvailability: { + mode: 'Disabled' + } + authConfig: { + activeDirectoryAuth: 'Enabled' + passwordAuth: 'Enabled' + tenantId: subscription().tenantId + } + } +} + +resource database 'Microsoft.DBforPostgreSQL/flexibleServers/databases@2023-12-01-preview' = { + parent: pgServer + name: databaseName + properties: { + charset: 'UTF8' + collation: 'en_US.utf8' + } +} + +resource firewallAzure 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-12-01-preview' = { + parent: pgServer + name: 'AllowAzureServices' + properties: { + startIpAddress: '0.0.0.0' + endIpAddress: '0.0.0.0' + } +} + +resource pgBouncer 'Microsoft.DBforPostgreSQL/flexibleServers/configurations@2023-12-01-preview' = { + parent: pgServer + name: 'pgbouncer.enabled' + properties: { + value: 'True' + source: 'user-override' + } +} + +output id string = pgServer.id +output fqdn string = pgServer.properties.fullyQualifiedDomainName +output databaseName string = database.name +``` + +### AAD Administrator + +```bicep +@description('AAD admin object ID') +param aadAdminObjectId string + +@description('AAD admin display name') +param aadAdminName string + +resource aadAdmin 'Microsoft.DBforPostgreSQL/flexibleServers/administrators@2023-12-01-preview' = { + parent: pgServer + name: aadAdminObjectId + properties: { + principalName: aadAdminName + principalType: 'ServicePrincipal' + tenantId: subscription().tenantId + } +} +``` + +### RBAC Assignment + +No ARM RBAC for data access -- use AAD database roles (see Terraform section SQL commands above). + +## Application Code + +### Python -- psycopg with Azure AD + +```python +from azure.identity import DefaultAzureCredential +import psycopg + +credential = DefaultAzureCredential() +token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") + +# Use PgBouncer port (6432) when PgBouncer is enabled +conn = psycopg.connect( + host=".postgres.database.azure.com", + port=6432, # PgBouncer port; use 5432 for direct connection + dbname="appdb", + user="my-app-identity", # AAD principal name + password=token.token, + sslmode="require", +) + +with conn.cursor() as cur: + cur.execute("SELECT * FROM items WHERE category = %s", ("electronics",)) + rows = cur.fetchall() +``` + +### Python -- pgvector for embeddings + +```python +from azure.identity import DefaultAzureCredential +import psycopg +from pgvector.psycopg import register_vector + +credential = DefaultAzureCredential() +token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") + +conn = psycopg.connect( + host=".postgres.database.azure.com", + dbname="appdb", + user="my-app-identity", + password=token.token, + sslmode="require", +) +register_vector(conn) + +with conn.cursor() as cur: + # Create vector extension and table + cur.execute("CREATE EXTENSION IF NOT EXISTS vector") + cur.execute(""" + CREATE TABLE IF NOT EXISTS documents ( + id SERIAL PRIMARY KEY, + content TEXT, + embedding vector(1536) + ) + """) + + # Similarity search + embedding = [0.1] * 1536 # From Azure OpenAI + cur.execute( + "SELECT id, content FROM documents ORDER BY embedding <=> %s::vector LIMIT 5", + (embedding,), + ) + results = cur.fetchall() +``` + +### C# -- Npgsql with Azure AD + +```csharp +using Azure.Identity; +using Npgsql; + +var credential = new DefaultAzureCredential(); +var token = await credential.GetTokenAsync( + new Azure.Core.TokenRequestContext(new[] { "https://ossrdbms-aad.database.windows.net/.default" }) +); + +var connString = new NpgsqlConnectionStringBuilder +{ + Host = ".postgres.database.azure.com", + Port = 6432, // PgBouncer port + Database = "appdb", + Username = "my-app-identity", + Password = token.Token, + SslMode = SslMode.Require, +}.ConnectionString; + +await using var conn = new NpgsqlConnection(connString); +await conn.OpenAsync(); +``` + +### Node.js -- pg with Azure AD + +```javascript +const { DefaultAzureCredential } = require("@azure/identity"); +const { Client } = require("pg"); + +const credential = new DefaultAzureCredential(); +const token = await credential.getToken("https://ossrdbms-aad.database.windows.net/.default"); + +const client = new Client({ + host: ".postgres.database.azure.com", + port: 6432, // PgBouncer port + database: "appdb", + user: "my-app-identity", + password: token.token, + ssl: { rejectUnauthorized: true }, +}); + +await client.connect(); +const res = await client.query("SELECT * FROM items WHERE category = $1", ["electronics"]); +``` + +## Common Pitfalls + +| Pitfall | Impact | Prevention | +|---------|--------|-----------| +| VNet integration set at creation time | Cannot switch between public access and VNet integration after creation | Decide networking model before deploying; POC can start with public access | +| AAD role creation requires admin SQL | Cannot create AAD database roles via Terraform/Bicep | Post-deployment step: connect as AAD admin and run SQL to create roles | +| Token refresh for long connections | AAD tokens expire after ~1 hour; connections fail | Implement token refresh callbacks or use short-lived connections with pooling | +| PgBouncer port vs direct port | Using wrong port causes connection failures | Use port 6432 for PgBouncer (recommended); port 5432 for direct connections | +| Extensions not allowlisted | `CREATE EXTENSION` fails even for supported extensions | Set `azure.extensions` server configuration before creating extensions | +| Burstable tier limitations | Limited IOPS; credits deplete under sustained load | Monitor CPU credits; upgrade to General Purpose for production loads | +| Storage auto-grow is one-way | Storage can grow but never shrink | Start with 32 GiB for POC to minimize committed storage | +| Firewall 0.0.0.0 rule scope | Allows ALL Azure services, not just your subscription | Use VNet integration or private endpoints for production isolation | +| Stopped server auto-start | Server auto-starts after 7 days if stopped | Schedule stops in automation; cannot stop indefinitely | +| Missing `GRANT DEFAULT PRIVILEGES` | New tables not accessible to AAD roles | Always run `ALTER DEFAULT PRIVILEGES` when granting schema access | + +## Production Backlog Items + +| Item | Priority | Description | +|------|----------|-------------| +| VNet integration or private endpoint | P1 | Migrate to delegated subnet or private endpoint and disable public access | +| Zone-redundant HA | P1 | Enable zone-redundant high availability for automatic failover | +| Upgrade to General Purpose tier | P2 | Move from Burstable to D-series for consistent performance | +| Disable password authentication | P1 | Switch to AAD-only authentication after setup | +| Enable PgBouncer | P2 | Enable built-in PgBouncer for connection pooling (port 6432) | +| Read replicas | P3 | Configure read replicas for read-heavy workloads and reporting | +| Geo-redundant backup | P2 | Enable geo-redundant backups for cross-region disaster recovery | +| Diagnostic settings | P2 | Route PostgreSQL logs and metrics to Log Analytics | +| Maintenance window | P3 | Schedule maintenance to low-traffic periods | +| Server parameter tuning | P3 | Tune work_mem, shared_buffers, max_connections based on workload | +| Connection pooling optimization | P3 | Tune PgBouncer pool_mode and connection limits | +| pgvector index strategy | P3 | Create HNSW or IVFFlat indexes for vector similarity search performance | diff --git a/azext_prototype/knowledge/services/postgresql.md b/azext_prototype/knowledge/services/postgresql.md deleted file mode 100644 index 03cefca..0000000 --- a/azext_prototype/knowledge/services/postgresql.md +++ /dev/null @@ -1,359 +0,0 @@ -# Azure Database for PostgreSQL (Flexible Server) -> Fully managed PostgreSQL database service with built-in high availability, automated backups, and intelligent performance optimization. - -## When to Use - -- **Relational data with PostgreSQL preference** -- teams with PostgreSQL expertise or existing PostgreSQL applications -- **Open-source ecosystem** -- leverage PostgreSQL extensions (PostGIS, pg_trgm, pgvector, etc.) -- **Vector search with pgvector** -- lightweight RAG scenarios without a separate search service -- **Python / Node.js applications** -- PostgreSQL is the most popular relational DB in these ecosystems -- **Migration from on-premises PostgreSQL** -- near drop-in compatibility - -Choose PostgreSQL Flexible Server over Azure SQL when the team prefers PostgreSQL, needs specific extensions, or has existing PostgreSQL tooling. Choose Azure SQL for .NET-heavy stacks or when SQL Server features (temporal tables, columnstore) are needed. - -## POC Defaults - -| Setting | Value | Notes | -|---------|-------|-------| -| SKU | Burstable B1ms | 1 vCore, 2 GiB RAM; lowest cost for POC | -| Storage | 32 GiB | Minimum; auto-grow enabled | -| PostgreSQL version | 16 | Latest stable | -| High availability | Disabled | POC doesn't need zone-redundant HA | -| Backup retention | 7 days | Default; sufficient for POC | -| Authentication | Azure AD + password | AAD for app, password for admin bootstrap | -| Public network access | Enabled (POC) | Flag private access as production backlog item | - -## Terraform Patterns - -### Basic Resource - -```hcl -resource "azurerm_postgresql_flexible_server" "this" { - name = var.name - location = var.location - resource_group_name = var.resource_group_name - version = "16" - sku_name = "B_Standard_B1ms" # Burstable tier - storage_mb = 32768 # 32 GiB - auto_grow_enabled = true - backup_retention_days = 7 - geo_redundant_backup_enabled = false - public_network_access_enabled = true # Set false when using private access - - authentication { - active_directory_auth_enabled = true - password_auth_enabled = true # Needed for initial admin; disable later - tenant_id = data.azurerm_client_config.current.tenant_id - } - - administrator_login = var.admin_username - administrator_password = var.admin_password # Store in Key Vault - - tags = var.tags -} - -# Required: Allow Azure services (for managed identity connections) -resource "azurerm_postgresql_flexible_server_firewall_rule" "azure_services" { - name = "AllowAzureServices" - server_id = azurerm_postgresql_flexible_server.this.id - start_ip_address = "0.0.0.0" - end_ip_address = "0.0.0.0" -} - -# Create application database -resource "azurerm_postgresql_flexible_server_database" "app" { - name = var.database_name - server_id = azurerm_postgresql_flexible_server.this.id - charset = "UTF8" - collation = "en_US.utf8" -} -``` - -### RBAC Assignment - -PostgreSQL Flexible Server uses **Azure AD authentication** at the database level, not Azure RBAC role assignments on the ARM resource. After deployment, grant database access via SQL: - -```sql --- Run as AAD admin after server creation --- Grant access to a managed identity -SELECT * FROM pgaad_list_principals(false); - --- Create AAD role for the managed identity -CREATE ROLE "my-app-identity" LOGIN IN ROLE azure_ad_user; - --- Grant permissions -GRANT ALL ON DATABASE appdb TO "my-app-identity"; -GRANT ALL ON ALL TABLES IN SCHEMA public TO "my-app-identity"; -ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "my-app-identity"; -``` - -ARM-level RBAC (for management operations): - -```hcl -# Contributor role for managing the server (not data access) -resource "azurerm_role_assignment" "pg_contributor" { - scope = azurerm_postgresql_flexible_server.this.id - role_definition_name = "Contributor" - principal_id = var.admin_identity_principal_id -} -``` - -### Private Endpoint - -PostgreSQL Flexible Server supports **VNet integration** (delegated subnet) as the primary private access method, not traditional private endpoints: - -```hcl -# Delegated subnet for PostgreSQL -resource "azurerm_subnet" "postgres" { - name = "snet-postgres" - resource_group_name = var.resource_group_name - virtual_network_name = var.vnet_name - address_prefixes = [var.postgres_subnet_cidr] - - delegation { - name = "postgresql" - service_delegation { - name = "Microsoft.DBforPostgreSQL/flexibleServers" - actions = ["Microsoft.Network/virtualNetworks/subnets/join/action"] - } - } -} - -# Private DNS zone for VNet-integrated server -resource "azurerm_private_dns_zone" "postgres" { - name = "${var.name}.private.postgres.database.azure.com" - resource_group_name = var.resource_group_name -} - -resource "azurerm_private_dns_zone_virtual_network_link" "postgres" { - name = "vnet-link" - resource_group_name = var.resource_group_name - private_dns_zone_name = azurerm_private_dns_zone.postgres.name - virtual_network_id = var.vnet_id -} - -# Server with VNet integration -resource "azurerm_postgresql_flexible_server" "this" { - # ... (same as basic, plus:) - delegated_subnet_id = azurerm_subnet.postgres.id - private_dns_zone_id = azurerm_private_dns_zone.postgres.id - public_network_access_enabled = false -} -``` - -Private DNS zone: `privatelink.postgres.database.azure.com` (for private endpoint) or `.private.postgres.database.azure.com` (for VNet integration) - -## Bicep Patterns - -### Basic Resource - -```bicep -@description('Name of the PostgreSQL server') -param name string - -@description('Azure region') -param location string = resourceGroup().location - -@description('Administrator login') -@secure() -param adminLogin string - -@description('Administrator password') -@secure() -param adminPassword string - -@description('Database name') -param databaseName string = 'appdb' - -@description('Tags to apply') -param tags object = {} - -resource pgServer 'Microsoft.DBforPostgreSQL/flexibleServers@2023-12-01-preview' = { - name: name - location: location - tags: tags - sku: { - name: 'Standard_B1ms' - tier: 'Burstable' - } - properties: { - version: '16' - administratorLogin: adminLogin - administratorLoginPassword: adminPassword - storage: { - storageSizeGB: 32 - autoGrow: 'Enabled' - } - backup: { - backupRetentionDays: 7 - geoRedundantBackup: 'Disabled' - } - highAvailability: { - mode: 'Disabled' - } - authConfig: { - activeDirectoryAuth: 'Enabled' - passwordAuth: 'Enabled' - tenantId: subscription().tenantId - } - } -} - -resource database 'Microsoft.DBforPostgreSQL/flexibleServers/databases@2023-12-01-preview' = { - parent: pgServer - name: databaseName - properties: { - charset: 'UTF8' - collation: 'en_US.utf8' - } -} - -resource firewallAzure 'Microsoft.DBforPostgreSQL/flexibleServers/firewallRules@2023-12-01-preview' = { - parent: pgServer - name: 'AllowAzureServices' - properties: { - startIpAddress: '0.0.0.0' - endIpAddress: '0.0.0.0' - } -} - -output id string = pgServer.id -output fqdn string = pgServer.properties.fullyQualifiedDomainName -output databaseName string = database.name -``` - -### RBAC Assignment - -No ARM RBAC for data access -- use AAD database roles (see Terraform section above). - -### Private Endpoint - -```bicep -@description('Delegated subnet ID for PostgreSQL VNet integration') -param delegatedSubnetId string = '' - -@description('Private DNS zone ID') -param privateDnsZoneId string = '' - -// When using VNet integration, set these on the server properties: -// delegatedSubnetId: delegatedSubnetId -// privateDnsZoneArmResourceId: privateDnsZoneId -// Note: VNet integration must be set at creation time; cannot be changed after. -``` - -## Application Code - -### Python — psycopg2 with Azure AD - -```python -from azure.identity import DefaultAzureCredential -import psycopg2 - -credential = DefaultAzureCredential() -token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default") - -conn = psycopg2.connect( - host=".postgres.database.azure.com", - database="appdb", - user="my-app-identity", # AAD principal name - password=token.token, - sslmode="require", -) - -cursor = conn.cursor() -cursor.execute("SELECT * FROM items WHERE category = %s", ("electronics",)) -rows = cursor.fetchall() -``` - -### Python — asyncpg with Azure AD - -```python -from azure.identity.aio import DefaultAzureCredential -import asyncpg - -credential = DefaultAzureCredential() -token = await credential.get_token("https://ossrdbms-aad.database.windows.net/.default") - -conn = await asyncpg.connect( - host=".postgres.database.azure.com", - database="appdb", - user="my-app-identity", - password=token.token, - ssl="require", -) - -rows = await conn.fetch("SELECT * FROM items WHERE category = $1", "electronics") -``` - -### C# — Npgsql with Azure AD - -```csharp -using Azure.Identity; -using Npgsql; - -var credential = new DefaultAzureCredential(); -var token = await credential.GetTokenAsync( - new Azure.Core.TokenRequestContext(new[] { "https://ossrdbms-aad.database.windows.net/.default" }) -); - -var connString = new NpgsqlConnectionStringBuilder -{ - Host = ".postgres.database.azure.com", - Database = "appdb", - Username = "my-app-identity", - Password = token.Token, - SslMode = SslMode.Require, -}.ConnectionString; - -await using var conn = new NpgsqlConnection(connString); -await conn.OpenAsync(); - -await using var cmd = new NpgsqlCommand("SELECT * FROM items WHERE category = @cat", conn); -cmd.Parameters.AddWithValue("cat", "electronics"); -await using var reader = await cmd.ExecuteReaderAsync(); -``` - -### Node.js — pg with Azure AD - -```javascript -const { DefaultAzureCredential } = require("@azure/identity"); -const { Client } = require("pg"); - -const credential = new DefaultAzureCredential(); -const token = await credential.getToken("https://ossrdbms-aad.database.windows.net/.default"); - -const client = new Client({ - host: ".postgres.database.azure.com", - database: "appdb", - user: "my-app-identity", - password: token.token, - ssl: { rejectUnauthorized: true }, - port: 5432, -}); - -await client.connect(); -const res = await client.query("SELECT * FROM items WHERE category = $1", ["electronics"]); -``` - -## Common Pitfalls - -1. **VNet integration is set at creation time** -- Cannot switch between public access and VNet integration after server creation. Decide upfront. For POC, start with public access and firewall rules. -2. **AAD role creation requires AAD admin** -- You must first set an AAD administrator on the server, then connect as that admin to create AAD database roles. This is a post-deployment step that cannot be done in Terraform/Bicep alone. -3. **Token refresh for long-running connections** -- Azure AD tokens expire after ~1 hour. Connection pools must refresh tokens. Use libraries that support token callback (Npgsql 8+ has built-in support). -4. **pgvector extension must be explicitly enabled** -- `CREATE EXTENSION vector;` is required before using vector types. Not enabled by default. -5. **Burstable tier limitations** -- B1ms has 1 vCore and limited IOPS. Fine for POC, but production workloads need General Purpose (D-series) or Memory Optimized (E-series). -6. **Storage auto-grow is one-way** -- Storage can grow automatically but cannot shrink. Start with the minimum (32 GiB) for POC. -7. **Firewall rule for Azure services** -- The `0.0.0.0` rule allows all Azure services, not just your subscription. For production, use VNet integration or private endpoint. - -## Production Backlog Items - -- [ ] Migrate to VNet integration (delegated subnet) and disable public access -- [ ] Enable zone-redundant high availability -- [ ] Upgrade from Burstable to General Purpose tier -- [ ] Disable password authentication (AAD-only) -- [ ] Configure connection pooling with PgBouncer (built-in) -- [ ] Set up read replicas for read-heavy workloads -- [ ] Configure diagnostic settings for query performance insights -- [ ] Implement automated maintenance window scheduling -- [ ] Add geo-redundant backup for disaster recovery -- [ ] Review and tune server parameters (work_mem, shared_buffers, etc.) diff --git a/azext_prototype/knowledge/services/private-dns-zone-a-record.md b/azext_prototype/knowledge/services/private-dns-zone-a-record.md new file mode 100644 index 0000000..d39e9c7 --- /dev/null +++ b/azext_prototype/knowledge/services/private-dns-zone-a-record.md @@ -0,0 +1,92 @@ +--- +service_namespace: Microsoft.Network/privateDnsZones/A +display_name: Private DNS Zone A Record +depends_on: + - Microsoft.Network/privateDnsZones +--- + +# Private DNS Zone A Record + +> An A record in a private DNS zone that maps a hostname to a private IPv4 address for VNet-internal name resolution. Most commonly auto-created by private endpoint DNS zone groups. + +## When to Use +- Manual A records for VNet-internal service discovery (e.g., custom hostnames for VMs) +- Override public DNS resolution with private IPs within a VNet +- Usually auto-managed by private endpoint DNS zone groups — manual creation is the exception +- Custom split-horizon DNS for hybrid connectivity scenarios + +## POC Defaults +- **TTL**: 300 seconds +- **Records**: Single private IPv4 address +- **Auto-registration**: Disabled (DNS zone group handles private endpoint records) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "private_dns_a_record" { + type = "Microsoft.Network/privateDnsZones/A@2024-06-01" + name = var.record_name + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + ttl = 300 + aRecords = [ + { ipv4Address = var.private_ip } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Private DNS Zone Contributor role allows managing records within a private zone. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param recordName string +param privateIp string +param ttl int = 300 + +resource aRecord 'Microsoft.Network/privateDnsZones/A@2024-06-01' = { + parent: privateDnsZone + name: recordName + properties: { + ttl: ttl + aRecords: [ + { ipv4Address: privateIp } + ] + } +} + +output fqdn string = '${recordName}.${privateDnsZone.name}' +``` + +## Application Code + +### Python +Infrastructure — transparent to application code + +### C# +Infrastructure — transparent to application code + +### Node.js +Infrastructure — transparent to application code + +## Common Pitfalls +- **Property casing differs from public DNS**: Private DNS zones use lowercase `ttl` and `aRecords`, while public DNS zones use `TTL` and `ARecords`. Mixing casing causes deployment failures. +- **Auto-registration conflicts**: If auto-registration is enabled on a VNet link, manually created records for VM names may conflict with auto-registered records. +- **DNS zone group is preferred**: For private endpoints, use a DNS zone group (private endpoint child resource) instead of manually creating A records. Zone groups auto-manage record lifecycle. +- **VNet link required**: The private DNS zone must be linked to the VNet for resolution to work. Records exist but don't resolve without the link. +- **No alias records**: Private DNS zones do not support alias/targetResource records. Only static A records are supported. + +## Production Backlog Items +- DNS zone group automation for all private endpoints +- VNet link management across hub-spoke topologies +- DNS resolution monitoring and health checks +- Record lifecycle automation for VM scale sets diff --git a/azext_prototype/knowledge/services/private-dns-zone-vnet-link.md b/azext_prototype/knowledge/services/private-dns-zone-vnet-link.md new file mode 100644 index 0000000..69df648 --- /dev/null +++ b/azext_prototype/knowledge/services/private-dns-zone-vnet-link.md @@ -0,0 +1,95 @@ +--- +service_namespace: Microsoft.Network/privateDnsZones/virtualNetworkLinks +display_name: Private DNS Zone VNet Link +depends_on: + - Microsoft.Network/privateDnsZones + - Microsoft.Network/virtualNetworks +--- + +# Private DNS Zone VNet Link + +> Links a private DNS zone to a VNet, enabling resources in that VNet to resolve private endpoint DNS records. + +## When to Use +- Every private DNS zone must be linked to the VNet where resources need resolution +- One link per VNet per DNS zone +- Auto-registration should be disabled for private endpoint DNS zones + +## POC Defaults +- **Registration enabled**: false (private endpoints manage their own DNS records) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "dns_vnet_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01" + name = var.link_name + location = "global" + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = azapi_resource.virtual_network.id + } + registrationEnabled = false + } + } + + tags = var.tags +} +``` + +### RBAC Assignment +```hcl +# Managed via the parent DNS zone's RBAC. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param linkName string +param vnetId string + +resource vnetLink 'Microsoft.Network/privateDnsZones/virtualNetworkLinks@2020-06-01' = { + parent: privateDnsZone + name: linkName + location: 'global' + properties: { + virtualNetwork: { + id: vnetId + } + registrationEnabled: false + } +} +``` + +## Application Code + +### Python +```python +# VNet links are infrastructure — transparent to application code. +``` + +### C# +```csharp +// VNet links are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// VNet links are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Location must be "global"**: Same as the parent DNS zone — always global. +- **Registration enabled false**: For private endpoint zones, always set `registrationEnabled = false`. Auto-registration is for VM DNS records, not private endpoints. +- **One link per VNet**: You cannot create multiple links from the same DNS zone to the same VNet. +- **Link name uniqueness**: Link names must be unique within the DNS zone. + +## Production Backlog Items +- Hub-and-spoke VNet link topology for centralized DNS resolution +- Link monitoring for resolution health +- Cross-subscription VNet links for shared services architecture diff --git a/azext_prototype/knowledge/services/private-dns-zone.md b/azext_prototype/knowledge/services/private-dns-zone.md new file mode 100644 index 0000000..98b32fc --- /dev/null +++ b/azext_prototype/knowledge/services/private-dns-zone.md @@ -0,0 +1,86 @@ +--- +service_namespace: Microsoft.Network/privateDnsZones +display_name: Private DNS Zone +depends_on: [] +--- + +# Private DNS Zone + +> Provides name resolution within a VNet for private endpoints. Each Azure service has a specific private DNS zone FQDN (e.g., privatelink.database.windows.net). + +## When to Use +- Required for every private endpoint to resolve the service's private IP +- One DNS zone per service type, linked to the VNet +- Created in the Networking stage alongside VNets and private endpoints + +## POC Defaults +- **Zone names**: Use exact Microsoft-documented FQDNs (e.g., `privatelink.vaultcore.azure.net`) +- **VNet link**: Auto-registration disabled (private endpoints handle DNS records) + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "private_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2020-06-01" + name = var.zone_name # e.g., "privatelink.database.windows.net" + location = "global" + parent_id = var.resource_group_id + + tags = var.tags +} +``` + +### RBAC Assignment +```hcl +# Private DNS Zone Contributor for zone management: +# b12aa53e-6015-4669-85d0-8515ebb5ae50 +``` + +## Bicep Patterns + +### Basic Resource +```bicep +param zoneName string +param tags object = {} + +resource privateDnsZone 'Microsoft.Network/privateDnsZones@2020-06-01' = { + name: zoneName + location: 'global' + tags: tags +} + +output zoneId string = privateDnsZone.id +output zoneName string = privateDnsZone.name +``` + +## Application Code + +### Python +```python +# Private DNS zones are infrastructure — transparent to application code. +# Applications connect using the standard service FQDN (e.g., myserver.database.windows.net) +# and DNS resolution automatically routes to the private IP via the private DNS zone. +``` + +### C# +```csharp +// Private DNS zones are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// Private DNS zones are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Zone names are exact FQDNs**: Use the exact Microsoft-documented zone name. For example, `privatelink.database.windows.net` (not `database.windows.net` or a custom name). +- **Location must be "global"**: Private DNS zones are always global resources. Setting a region will fail. +- **VNet link required**: The DNS zone must be linked to the VNet for resolution to work. Without the link, private endpoint DNS records are invisible. +- **One zone per service type**: Do not create separate zones per resource instance. One `privatelink.vaultcore.azure.net` zone serves all Key Vault private endpoints. + +## Production Backlog Items +- Conditional forwarder integration for hybrid DNS (on-premises resolution) +- Multiple VNet links for hub-and-spoke topology +- DNS zone monitoring for resolution failures +- Cross-region DNS zone configuration for geo-redundancy diff --git a/azext_prototype/knowledge/services/private-endpoint-dns-zone-group.md b/azext_prototype/knowledge/services/private-endpoint-dns-zone-group.md new file mode 100644 index 0000000..aa4e171 --- /dev/null +++ b/azext_prototype/knowledge/services/private-endpoint-dns-zone-group.md @@ -0,0 +1,99 @@ +--- +service_namespace: Microsoft.Network/privateEndpoints/privateDnsZoneGroups +display_name: Private Endpoint DNS Zone Group +depends_on: + - Microsoft.Network/privateEndpoints + - Microsoft.Network/privateDnsZones +--- + +# Private Endpoint DNS Zone Group + +> Associates a private endpoint with one or more private DNS zones, automatically creating DNS A records that map the service FQDN to the private IP. + +## When to Use +- Every private endpoint needs a DNS zone group for name resolution +- Links the private endpoint's private IP to the correct DNS zone +- Without this, applications must use the private IP directly (fragile) + +## POC Defaults +- **Name**: "default" (convention) +- **DNS zone configs**: One per service's required DNS zone + +## Terraform Patterns + +### Basic Resource +```hcl +resource "azapi_resource" "pe_dns_zone_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01" + name = "default" + parent_id = azapi_resource.private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = azapi_resource.private_dns_zone.id + } + } + ] + } + } +} +``` + +### RBAC Assignment +```hcl +# Managed via the parent private endpoint's RBAC. +# Requires Network Contributor on both the PE and the DNS zone. +``` + +## Bicep Patterns + +### Basic Resource +```bicep +resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2024-01-01' = { + parent: privateEndpoint + name: 'default' + properties: { + privateDnsZoneConfigs: [ + { + name: 'config' + properties: { + privateDnsZoneId: privateDnsZone.id + } + } + ] + } +} +``` + +## Application Code + +### Python +```python +# DNS zone groups are infrastructure — transparent to application code. +# Once configured, the service FQDN (e.g., myserver.database.windows.net) +# resolves to the private IP automatically. +``` + +### C# +```csharp +// DNS zone groups are infrastructure — transparent to application code. +``` + +### Node.js +```typescript +// DNS zone groups are infrastructure — transparent to application code. +``` + +## Common Pitfalls +- **Name should be "default"**: While other names work, "default" is the convention and some Azure portal features expect it. +- **DNS zone must be linked to VNet**: The DNS zone group creates A records, but resolution only works if the DNS zone is also linked to the VNet via a VNet link. +- **One zone group per PE**: Each private endpoint has exactly one DNS zone group. Multiple DNS zone configs can be in the same group. +- **Config name uniqueness**: Each `privateDnsZoneConfigs` entry must have a unique name. + +## Production Backlog Items +- Multi-zone configurations for services with multiple DNS zones (e.g., Cosmos DB multi-API) +- Cross-region DNS zone group configuration for geo-redundant private endpoints diff --git a/azext_prototype/knowledge/services/private-endpoints.md b/azext_prototype/knowledge/services/private-endpoints.md new file mode 100644 index 0000000..a31f179 --- /dev/null +++ b/azext_prototype/knowledge/services/private-endpoints.md @@ -0,0 +1,258 @@ +--- +service_namespace: Microsoft.Network/privateEndpoints +display_name: Azure Private Endpoints +--- + +# Azure Private Endpoints +> Network interface that connects you privately and securely to a service powered by Azure Private Link, routing traffic over the Microsoft backbone network instead of the public internet. + +## When to Use + +- **Every production Azure deployment** -- private endpoints are the standard pattern for securing access to Azure PaaS services +- **Data exfiltration prevention** -- ensure traffic to Storage, SQL, Key Vault, etc. never traverses the public internet +- **Compliance requirements** -- regulations requiring private-only access to data services +- **Hub-spoke network topologies** -- connect spoke workloads to shared services via private IP addresses +- **Hybrid connectivity** -- on-premises clients accessing Azure services through VPN/ExpressRoute via private IPs + +Private endpoints are a **production backlog item** in POC deployments. During POC, public access is typically enabled for simplicity, but the private endpoint pattern should be documented and ready for production hardening. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Deployment | Deferred to production | POC uses public endpoints for simplicity | +| DNS integration | Private DNS zone | Required for name resolution of private endpoints | +| Approval | Auto-approved | Use manual approval for cross-tenant scenarios | +| Network policy | Disabled on subnet | NSG/UDR support for PE subnets is preview | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "private_endpoint" { + type = "Microsoft.Network/privateEndpoints@2023-11-01" + name = "pe-${var.service_name}" + location = var.location + parent_id = var.resource_group_id + + body = { + properties = { + subnet = { + id = var.subnet_id + } + privateLinkServiceConnections = [ + { + name = "psc-${var.service_name}" + properties = { + privateLinkServiceId = var.target_resource_id + groupIds = [var.group_id] # e.g., "blob", "vault", "sites", "sqlServer" + } + } + ] + } + } + + tags = var.tags +} + +resource "azapi_resource" "pe_dns_zone_group" { + type = "Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01" + name = "dns-zone-group" + parent_id = azapi_resource.private_endpoint.id + + body = { + properties = { + privateDnsZoneConfigs = [ + { + name = "config" + properties = { + privateDnsZoneId = var.private_dns_zone_id + } + } + ] + } + } +} +``` + +### Private DNS Zone + +```hcl +resource "azapi_resource" "private_dns_zone" { + type = "Microsoft.Network/privateDnsZones@2024-06-01" + name = var.dns_zone_name # e.g., "privatelink.blob.core.windows.net" + location = "global" + parent_id = var.resource_group_id + + tags = var.tags +} + +# Link DNS zone to VNet for name resolution +resource "azapi_resource" "dns_vnet_link" { + type = "Microsoft.Network/privateDnsZones/virtualNetworkLinks@2024-06-01" + name = "link-${var.vnet_name}" + location = "global" + parent_id = azapi_resource.private_dns_zone.id + + body = { + properties = { + virtualNetwork = { + id = var.vnet_id + } + registrationEnabled = false + } + } + + tags = var.tags +} +``` + +### Common Group IDs and DNS Zones + +```hcl +# Reference table for privateLinkServiceConnections groupIds and DNS zones: +# +# Service | groupId | Private DNS Zone +# -------------------------|------------------|------------------------------------------ +# Storage (Blob) | blob | privatelink.blob.core.windows.net +# Storage (File) | file | privatelink.file.core.windows.net +# Storage (Queue) | queue | privatelink.queue.core.windows.net +# Storage (Table) | table | privatelink.table.core.windows.net +# Key Vault | vault | privatelink.vaultcore.azure.net +# SQL Database | sqlServer | privatelink.database.windows.net +# PostgreSQL Flexible | postgresqlServer | privatelink.postgres.database.azure.com +# MySQL Flexible | mysqlServer | privatelink.mysql.database.azure.com +# Cosmos DB | Sql | privatelink.documents.azure.com +# App Service / Functions | sites | privatelink.azurewebsites.net +# Container Registry | registry | privatelink.azurecr.io +# Redis Cache | redisCache | privatelink.redis.cache.windows.net +# Event Hubs | namespace | privatelink.servicebus.windows.net +# Service Bus | namespace | privatelink.servicebus.windows.net +# SignalR | signalr | privatelink.service.signalr.net +# Azure OpenAI | account | privatelink.openai.azure.com +# Cognitive Services | account | privatelink.cognitiveservices.azure.com +# Azure ML Workspace | amlworkspace | privatelink.api.azureml.ms +# Azure Search | searchService | privatelink.search.windows.net +``` + +### RBAC Assignment + +```hcl +# Private endpoints do not have their own data-plane RBAC. +# RBAC is controlled on the target resource (e.g., Storage, Key Vault). +# The private endpoint simply provides a private network path. +# +# Network Contributor on the subnet is needed for the deploying identity: +resource "azapi_resource" "subnet_network_contributor" { + type = "Microsoft.Authorization/roleAssignments@2022-04-01" + name = uuidv5("oid", "${var.subnet_id}${var.deployer_principal_id}network-contributor") + parent_id = var.subnet_id + + body = { + properties = { + roleDefinitionId = "/subscriptions/${var.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/4d97b98b-1d4f-4787-a291-c67834d212e7" # Network Contributor + principalId = var.deployer_principal_id + principalType = "ServicePrincipal" + } + } +} +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the private endpoint') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Subnet ID for the private endpoint') +param subnetId string + +@description('Target resource ID to connect to') +param targetResourceId string + +@description('Private link group ID (e.g., blob, vault, sites)') +param groupId string + +@description('Private DNS zone ID for DNS registration') +param privateDnsZoneId string + +@description('Tags to apply') +param tags object = {} + +resource privateEndpoint 'Microsoft.Network/privateEndpoints@2023-11-01' = { + name: name + location: location + tags: tags + properties: { + subnet: { + id: subnetId + } + privateLinkServiceConnections: [ + { + name: 'psc-${name}' + properties: { + privateLinkServiceId: targetResourceId + groupIds: [groupId] + } + } + ] + } +} + +resource dnsZoneGroup 'Microsoft.Network/privateEndpoints/privateDnsZoneGroups@2023-11-01' = { + parent: privateEndpoint + name: 'dns-zone-group' + properties: { + privateDnsZoneConfigs: [ + { + name: 'config' + properties: { + privateDnsZoneId: privateDnsZoneId + } + } + ] + } +} + +output id string = privateEndpoint.id +output name string = privateEndpoint.name +output networkInterfaceId string = privateEndpoint.properties.networkInterfaces[0].id +``` + +### RBAC Assignment + +```bicep +// Private endpoints rely on RBAC of the target resource. +// No specific PE RBAC roles needed. +// Ensure the deploying identity has Network Contributor on the subnet. +``` + +## Common Pitfalls + +| Pitfall | Impact | Fix | +|---------|--------|-----| +| Missing private DNS zone | Name resolution fails; clients cannot reach the private endpoint by FQDN | Create the correct `privatelink.*` DNS zone and link it to the VNet | +| DNS zone not linked to VNet | DNS queries from VNet do not resolve private endpoint IPs | Create `virtualNetworkLinks` from the DNS zone to each VNet that needs access | +| Not disabling public access on target | Traffic can still reach the service via public endpoint, bypassing the private endpoint | Set `publicNetworkAccess = "Disabled"` on the target resource | +| Wrong `groupId` | Private endpoint creation fails or connects to wrong sub-resource | Use the correct group ID from the reference table above | +| Subnet too small | Cannot create enough private endpoints | Plan subnet size: each PE uses one IP; /28 gives 11 usable IPs | +| Cross-region DNS resolution | Private DNS zones are global, but VNet links are per-VNet | Link DNS zones to all VNets that need resolution, including hub VNets | +| Forgetting on-premises DNS forwarding | On-premises clients cannot resolve `privatelink.*` FQDNs | Configure DNS forwarder in hub VNet; point on-premises DNS conditional forwarders to it | + +## Production Backlog Items + +- [ ] Create private endpoints for all PaaS services (Storage, Key Vault, SQL, etc.) +- [ ] Disable public network access on all target resources +- [ ] Centralize private DNS zones in hub subscription/resource group +- [ ] Configure DNS forwarding for hybrid (on-premises) connectivity +- [ ] Review subnet sizing for private endpoint capacity +- [ ] Set up monitoring for private endpoint connection status +- [ ] Document the group ID and DNS zone mapping for the architecture +- [ ] Configure NSG rules on private endpoint subnets (preview feature) +- [ ] Implement Azure Policy to enforce private endpoint usage on supported services diff --git a/azext_prototype/knowledge/services/public-ip-prefix.md b/azext_prototype/knowledge/services/public-ip-prefix.md new file mode 100644 index 0000000..d4ab1c8 --- /dev/null +++ b/azext_prototype/knowledge/services/public-ip-prefix.md @@ -0,0 +1,129 @@ +--- +service_namespace: Microsoft.Network/publicIPPrefixes +display_name: Public IP Prefix +--- + +# Public IP Prefix + +> Contiguous range of static public IP addresses reserved from Azure's pool, enabling predictable outbound IP ranges for firewall allowlisting and consistent NAT gateway addressing. + +## When to Use +- **NAT Gateway** -- assign a prefix to a NAT gateway for predictable outbound SNAT IPs from a known contiguous range +- **Firewall allowlisting** -- when partner or customer firewalls need a known, stable IP range to allowlist +- **Load balancer frontends** -- allocate multiple public IPs from a single prefix for load balancer rules +- **Azure Firewall** -- use a prefix for outbound SNAT with predictable IP ranges + +Public IP prefixes guarantee contiguous addresses. Individual public IPs allocated from a prefix share the same range and can be referenced by firewall rules on partner systems. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| Prefix length | /31 | 2 IPs; smallest useful range for POC | +| SKU | Standard | Only Standard is supported | +| Tier | Regional | Global for cross-region load balancing | +| IP version | IPv4 | IPv6 prefixes also available | +| Zone | Zone-redundant | For availability; or specific zone | + +## Terraform Patterns + +### Basic Resource + +```hcl +resource "azapi_resource" "ip_prefix" { + type = "Microsoft.Network/publicIPPrefixes@2024-01-01" + name = var.name + location = var.location + parent_id = var.resource_group_id + + body = { + sku = { + name = "Standard" + tier = "Regional" + } + properties = { + prefixLength = var.prefix_length # /28 = 16 IPs, /31 = 2 IPs + publicIPAddressVersion = "IPv4" + } + zones = var.availability_zones # e.g., ["1", "2", "3"] + } + + tags = var.tags + + response_export_values = ["properties.ipPrefix"] +} +``` + +### RBAC Assignment + +```hcl +# Network Contributor on the resource group covers public IP prefix management. +# Role ID: 4d97b98b-1d4f-4787-a291-c67834d212e7 +``` + +## Bicep Patterns + +### Basic Resource + +```bicep +@description('Name of the public IP prefix') +param name string + +@description('Azure region') +param location string = resourceGroup().location + +@description('Prefix length (e.g., 28 for 16 IPs, 31 for 2 IPs)') +@minValue(21) +@maxValue(31) +param prefixLength int = 31 + +param tags object = {} + +resource ipPrefix 'Microsoft.Network/publicIPPrefixes@2024-01-01' = { + name: name + location: location + tags: tags + sku: { + name: 'Standard' + tier: 'Regional' + } + properties: { + prefixLength: prefixLength + publicIPAddressVersion: 'IPv4' + } + zones: ['1', '2', '3'] +} + +output id string = ipPrefix.id +output ipPrefix string = ipPrefix.properties.ipPrefix +``` + +## Application Code + +### Python +Infrastructure -- transparent to application code. Public IP prefixes define network addressing; applications are unaware of the specific outbound IP addresses. + +### C# +Infrastructure -- transparent to application code. Public IP prefixes define network addressing; applications are unaware of the specific outbound IP addresses. + +### Node.js +Infrastructure -- transparent to application code. Public IP prefixes define network addressing; applications are unaware of the specific outbound IP addresses. + +## Common Pitfalls + +1. **Prefix length is immutable** -- Cannot resize a prefix after creation. If you need more IPs, create a new prefix. Plan capacity upfront. +2. **Only Standard SKU** -- Public IP prefixes only work with Standard SKU public IPs. Basic SKU IPs cannot be derived from a prefix. +3. **Region-locked** -- A prefix is tied to a region. Public IPs derived from it must be in the same region. +4. **Cost accrues immediately** -- You pay for all IPs in the prefix whether or not they are allocated to resources. A /28 prefix (16 IPs) costs 16x a single public IP. +5. **Deletion requires all IPs released** -- Cannot delete a prefix while any public IP derived from it is still in use. Deallocate all child IPs first. +6. **NAT Gateway limit** -- A NAT gateway supports up to 16 public IPs or prefixes. A /28 prefix counts as one, but a single prefix can provide up to 16 IPs. +7. **Zone selection is permanent** -- The availability zone assignment cannot be changed after creation. Zone-redundant is the safest default. + +## Production Backlog Items + +- [ ] Right-size prefix length based on expected outbound IP requirements +- [ ] Document the IP prefix range and share with partners for firewall allowlisting +- [ ] Configure DDoS Protection Standard on public IPs derived from the prefix +- [ ] Set up monitoring for IP allocation from the prefix +- [ ] Plan for IPv6 dual-stack prefix if required +- [ ] Evaluate Global tier for cross-region load balancing scenarios diff --git a/azext_prototype/knowledge/services/public-ip.md b/azext_prototype/knowledge/services/public-ip.md new file mode 100644 index 0000000..1f1f685 --- /dev/null +++ b/azext_prototype/knowledge/services/public-ip.md @@ -0,0 +1,254 @@ +--- +service_namespace: Microsoft.Network/publicIPAddresses +display_name: Azure Public IP Address +--- + +# Azure Public IP Address +> Static or dynamic public IPv4/IPv6 address resource used by load balancers, application gateways, VPN gateways, Bastion hosts, and virtual machines for internet-facing connectivity. + +## When to Use + +- **Internet-facing services** -- required by Application Gateway, Load Balancer, Azure Firewall, Bastion +- **VM direct internet access** -- attach to VM NIC for direct public connectivity (not recommended for production) +- **NAT Gateway** -- provides static outbound IP for subnet-level SNAT +- **VPN/ExpressRoute Gateway** -- required for gateway public endpoint +- **Static IP requirement** -- DNS A records, firewall allow-listing, partner integrations + +Public IP is a **foundational resource** -- it is consumed by other networking resources rather than used standalone. + +## POC Defaults + +| Setting | Value | Notes | +|---------|-------|-------| +| SKU | Standard | Basic is deprecated for new deployments | +| Allocation | Static | Required for Standard SKU | +| Version | IPv4 | IPv6 for dual-stack scenarios | +| Tier | Regional | Global for cross-region LB | +| Idle timeout | 4 minutes | Default; configurable 4-30 minutes | +| DNS label | Optional | Creates `