lab-shared-contract

name: lab-shared-contract description: Single source of truth for cross-cutting rules referenced by all agents and skills in the lab pipeline. Every requirement has a unique ID (R-0xx).

Shared Contract

Authoritative cross-cutting rules for the hands-on lab pipeline. Every requirement is identified by a unique ID (R-0xx). Other files MUST reference these IDs — never restate the rule.

For the full Azure governance implementation policy, see Governance-Lab.md at .assets/shared/Governance-Lab.md.

R-001: Resource Group Naming

Pattern: <exam>-<domain>-<topic>-<deployment>

• <exam>: lowercase exam code (az104, az305)
• <domain>: lowercase domain slug (e.g., networking, storage, generative-ai)
• <topic>: lowercase topic slug (e.g., vnet-peering, blob-versioning)
• <deployment>: tf | bicep | scripted

Example: az104-networking-vnet-peering-tf

R-002: Resource Naming — AZ-104 Prefixes

Pattern: <prefix>-<role>[-instance]

• <role> describes the resource's function in the lab scenario — NOT the lab topic (see R-031).

All names are static by default. Random suffixes are only added for resources subject to soft-delete retention (see R-028).

R-003: Resource Naming — AI-103 Prefixes

Pattern: <prefix>-<role>[-instance]

• <role> describes the resource's function in the lab scenario — NOT the lab topic (see R-031).

All names are static by default. Random suffixes are only added for resources subject to soft-delete retention (see R-028).

Cognitive Services resources (OpenAI, Multi-service, Vision, Language) require random suffix because they enter soft-deleted state on deletion — see R-028.

These prefixes apply to AI-103 labs. Legacy AI-102 artifacts also follow these conventions.

R-004: Bicep Stack Naming

Pattern: stack-<domain>-<topic>

No exam code in stack name.

R-005: Required Tags (All Resources)

R-006: Region Rules

Use eastus unless capacity requires fallback.

R-007: Infrastructure SKU Defaults

R-008: AI Service SKU Defaults

Start free tier when available.

R-009: Per-Lab Resource Limits

R-010: Lab Folder Structure

IaaC (Terraform)

<EXAM>/hands-on-labs/<domain>/lab-<topic>/
├── README.md
├── terraform/
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── providers.tf
│   ├── terraform.tfvars
│   └── modules/
│       └── <module>/
│           ├── main.tf
│           ├── variables.tf
│           └── outputs.tf
└── validation/
    └── <validation-script>.ps1

IaaC (Bicep)

<EXAM>/hands-on-labs/<domain>/lab-<topic>/
├── README.md
├── bicep/
│   ├── main.bicep
│   ├── main.bicepparam
│   ├── bicepconfig.json
│   ├── bicep.ps1
│   └── modules/
│       └── <module>.bicep
└── validation/
    └── <validation-script>.ps1

Scripted

<EXAM>/hands-on-labs/<domain>/lab-<topic>/
├── README.md
├── scripts/
│   ├── deploy.*
│   ├── config.* (if needed)
│   └── cleanup.*
└── validation/

Manual

<EXAM>/hands-on-labs/<domain>/lab-<topic>/
├── README.md
└── screenshots/ (optional)

R-011: README 14-Section Order

Every lab README must contain these sections in this exact sequence:

1. Exam Question Scenario / Exam Task (depends on Intake Mode)
2. Solution Architecture
3. Architecture Diagram
4. Lab Objectives
5. Lab Structure
6. Prerequisites
7. Deployment
8. Testing the Solution
9. Cleanup
10. Scenario Analysis / Task Deep Dive (depends on Intake Mode)
11. Key Learning Points
12. Related Objectives
13. Additional Resources
14. Related Labs

R-012: Code Header Block

Include in all .tf, .bicep, .ps1 files. Do NOT include in README.

# -------------------------------------------------------------------------
# Program: [filename]
# Description: [purpose]
# Context: [EXAM] Lab - [scenario]
# Author: Greg Tate
# Date: [YYYY-MM-DD]
# -------------------------------------------------------------------------

Use // for .bicep files, # for .tf and .ps1.

R-013: Mermaid Diagram Criteria

• Always required — every lab README must include a Mermaid diagram
• When 2+ interconnected resources are deployed, diagram the resource topology (dependencies, network paths, data flow)
• When fewer than 2 interconnected resources, diagram the overall process reflective of the exam question (e.g., data flow from source → service → output, access methods, decision paths)
• Use graph TD (top-down) for hierarchical layouts or graph LR (left-right) for pipeline / process flows
• Resource names must match governance naming conventions
• Show dependencies and relationships

R-014: Review Report Schema

## Review Summary
- Overall: [PASS | FAIL]
- Checks Passed: [X/Y]
- Critical Violations: [count]

## Detailed Results

### [Category Name]
- [Check]: PASS
- [Check]: FAIL — [issue and fix]

## Required Fixes (if FAIL)
1. [File]: [exact change]

R-015: Cleanup Policy

• Destroy lab resources within 7 days
• Track via DateCreated tag
• README cleanup section must reference 7-day policy
• Reference labs must justify permanence in README

R-016: Soft-Delete / Purge

Resources Requiring Purge

Only resources whose names are reserved during soft-delete retention require random suffixes (see R-028). All other resources use static names.

Disable Patterns

Terraform:

soft_delete_enabled                          = false
purge_soft_delete_on_destroy                 = false   # Unique names eliminate need to purge; false speeds up destroy
permanently_delete_on_destroy                = true    # Log Analytics
purge_protected_items_from_vault_on_destroy  = true    # Recovery Vault

Bicep:

softDeleteState: 'Disabled'

R-017: Deployment Method Priority

IaaC > Scripted > Manual

If IaaC, always ask user to choose Terraform or Bicep. Never auto-select.

R-018: IaaC Validation Sequence

1. Validate Syntax — terraform validate or bicep build
2. Regional Capacity Test — for constrained services (see R-019)
3. Final Validation — terraform plan or deployment preview

Terraform:

Use-AzProfile Lab
Test-Path terraform.tfvars
terraform init
terraform validate
terraform fmt
# Capacity tests here (R-019)
terraform plan

Bicep:

Use-AzProfile Lab
.\bicep.ps1 validate
# Capacity tests here (R-019)
.\bicep.ps1 plan

R-019: Capacity-Constrained Services

Services requiring regional capacity validation before deployment:

• Cosmos DB (Microsoft.DocumentDB)
• AI Search (Microsoft.Search)
• OpenAI / Cognitive Services (Microsoft.CognitiveServices)

Validation commands:

az provider show --namespace Microsoft.DocumentDB `
    --query "resourceTypes[?resourceType=='databaseAccounts'].locations[]"

az provider show --namespace Microsoft.Search `
    --query "resourceTypes[?resourceType=='searchServices'].locations[]"

az provider show --namespace Microsoft.CognitiveServices `
    --query "resourceTypes[?resourceType=='accounts'].locations[]"

If unavailable, use fallback regions per R-006.

R-020: Lab Subscription

e091f6e7-031a-4924-97bb-8c983ca5d21a

Must appear in:

• terraform.tfvars → lab_subscription_id
• Bicep → subscription context validation
• Validation scripts → subscription check

R-021: Language Style Conventions

R-022: Module Rule

Use modules when 2+ related resource types are deployed.

• Domain grouping (one concern per module)
• Self-contained with clear inputs/outputs
• Pass common_tags (TF) / commonTags (Bicep) to all modules
• Pass identity references (e.g., principal_id) as explicit inputs for RBAC
• Thin orchestration in root main.tf / main.bicep
• Anti-pattern: consolidating unrelated resource types into a single module

R-023: Common Tags Variable Pattern

Terraform:

locals {
  common_tags = {
    Environment      = "Lab"
    Project          = "<EXAM>"
    Domain           = "<Domain>"
    Purpose          = "<Purpose>"
    Owner            = var.owner
    DateCreated      = var.date_created
    DeploymentMethod = "Terraform"
  }
}

Bicep:

var commonTags = {
  Environment: 'Lab'
  Project: '<EXAM>'
  Domain: '<Domain>'
  Purpose: '<Purpose>'
  Owner: owner
  DateCreated: dateCreated
  DeploymentMethod: 'Bicep'
}

R-024: Password Generation

Must meet Azure complexity. Mark as @secure() (Bicep) or sensitive (Terraform). May be specified in a parameters file.

Terraform: Use hashicorp/random or supply via terraform.tfvars.

resource "random_password" "admin" {
  length           = 16
  special          = true
  override_special = "!@#$%"
}

Bicep: Use uniqueString(), static pattern, or supply in .bicepparam. Mark @secure().

Target pattern: AzureLab2026!

R-025: Azure Configuration Guardrails

• Load Balancer SNAT: Set disableOutboundSnat = true when frontend used for inbound + outbound
• NIC + Public IP: NIC with instance public IP cannot join outbound backend pool
• Storage Containers (TF): Use storage_account_id not storage_account_name
• AI Services: Enable public network access for labs; validate model availability per region; start minimal capacity; output keys as sensitive
• AI Agent RBAC: Requires both data plane + control plane roles (e.g., Cosmos DB Operator)

For full details, see Governance-Lab.md at .assets/shared/Governance-Lab.md.

R-026: Bastion Dependency Ordering (Required)

Azure Bastion Developer SKU requires the VNet to be in Succeeded state. Creating Bastion in parallel with subnet resources causes a BastionHostVirtualNetworkNotFound race condition.

Always declare an explicit dependency so Bastion creation waits for all networking resources to complete.

Terraform — add depends_on to the module that contains azurerm_bastion_host:

module "compute" {
  # ...
  depends_on = [module.networking]
}

Bicep — add dependsOn to the Bastion resource or module:

resource bastion 'Microsoft.Network/bastionHosts@2024-10-01' = {
  name: bastionName
  // ...
  dependsOn: [
    networkingModule
  ]
}

R-027: Static Names by Default

All resource names must be static and predictable unless the resource is subject to soft-delete name reservation (see R-028).

• Static name: A literal string with no runtime-generated components (uniqueString(), random_string, etc.).
• Storage accounts, VMs, VNets, NSGs, subnets, load balancers, and all other non-soft-delete resources use static names.
• This keeps README code blocks, architecture diagrams, and testing steps simple and reproducible.

R-028: Random Suffix — Soft-Delete Resources Only

Random suffixes are only permitted for resources that enter a soft-deleted state where the name is reserved during the retention period. These are listed in R-016.

Resources Requiring Random Suffix

Random Suffix Format

Bicep: '${resourcePrefix}${topic}${uniqueString(resourceGroup().id)}'

Terraform: "${resourcePrefix}-${topic}-${random_string.suffix.result}"

Length: 4 lowercase alphanumeric characters.

Resources That Do NOT Get Random Suffix

Even if globally unique (e.g., storage accounts), these resources do not need random suffixes because their names are released immediately on deletion:

• Storage Accounts
• AI Search
• Cosmos DB
• Log Analytics (soft-delete can be disabled)
• App Insights (soft-delete can be disabled)

R-029: README-to-IaC Resource Name Consistency

All resource names referenced in the README must exactly match the names defined in the IaC code. The README (authored in Phase 2) establishes the intended names. The IaC code (generated in Phase 3) must implement those same names.

This applies to all resource types: resource groups, VMs, storage accounts, VNets, NSGs, Key Vaults, and any other named Azure resource.

Scope

Enforcement

• The Lab-Reviewer (Phase 4) must cross-reference every resource name in the README against the corresponding name in the IaC code.
• Any mismatch — in either direction — is a Category 1 Naming Compliance FAIL.
• The fix must align the IaC name to the README, or update the README to reflect the actual IaC name, before delivery.
• If the IaC uses a random suffix for a resource that should have a static name per R-027/R-028, flag it as a Naming Compliance FAIL.

R-030: Command-Line Fidelity

All command-line snippets in README Testing the Solution, Deployment, and Validation sections must be syntactically correct and produce the stated expected output when run against the deployed resources.

What to Check

Enforcement

• The Lab-Reviewer (Phase 4) evaluates command-line fidelity as Category 11.
• A FAIL in Category 11 does not block delivery on its own, but each issue must include an actionable fix.
• Common violations: wrong property names, unexpanded nested objects, stale API versions, invalid parameter names.

R-031: Role-Based Resource Names (No Topic Echo)

Resource names must describe the resource's role or function in the lab scenario — never echo the lab topic.

Why

When every resource is named <prefix>-<topic>, the names imply each resource IS the concept being studied rather than a resource that DEMONSTRATES the concept. This creates confusion, especially for resources that configure or contain the feature under study.

Rule

• The resource group retains the topic-based name per R-001 (e.g., az104-compute-keda-scaling-rule-bicep).
• Individual resources within the lab use scenario-appropriate role names that describe what the resource does.
• Each resource should have a distinct, practical name — avoid giving every resource the same suffix.

Examples

Lab: lab-keda-scaling-rule (Container App with KEDA scaling)

Lab: lab-vnet-peering (Two peered VNets)

Lab: lab-blob-versioning (Storage with versioning enabled)

Choosing Good Role Names

• Ask: "What does this resource represent in the scenario?" — not "What concept does this lab teach?"
• Draw names from the workload domain: orders, web-frontend, monitoring, hub, spoke, documents, media, inventory.
• Supporting infrastructure can use generic role names: law-monitoring, cae-lab, nsg-default.
• Keep names short (1–2 words after the prefix).