mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-23 03:45:13 +00:00
Add azure deployment preflight skill
This commit is contained in:
Tom Meschter (from Dev Box)
392
skills/azure-deployment-preflight/references/ERROR-HANDLING.md
Normal file
392
skills/azure-deployment-preflight/references/ERROR-HANDLING.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# Error Handling Guide
|
||||
|
||||
This reference documents common errors during preflight validation and how to handle them.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Continue on failure.** Capture all issues in the final report rather than stopping at the first error. This gives users a complete picture of what needs to be fixed.
|
||||
|
||||
---
|
||||
|
||||
## Authentication Errors
|
||||
|
||||
### Not Logged In (Azure CLI)
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
ERROR: Please run 'az login' to setup account.
|
||||
ERROR: AADSTS700082: The refresh token has expired
|
||||
```
|
||||
|
||||
**Exit Codes:** Non-zero
|
||||
|
||||
**Handling:**
|
||||
1. Note the error in the report
|
||||
2. Include remediation steps
|
||||
3. Skip remaining Azure CLI commands
|
||||
4. Continue with other validation steps if possible
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ❌ Azure CLI Authentication Required
|
||||
|
||||
- **Severity:** Error
|
||||
- **Source:** az cli
|
||||
- **Message:** Not logged in to Azure CLI
|
||||
- **Remediation:** Run `az login` to authenticate, then re-run preflight validation
|
||||
- **Documentation:** https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cli
|
||||
```
|
||||
|
||||
### Not Logged In (azd)
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
ERROR: not logged in, run `azd auth login` to login
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note the error in the report
|
||||
2. Skip azd commands
|
||||
3. Suggest `azd auth login`
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ❌ Azure Developer CLI Authentication Required
|
||||
|
||||
- **Severity:** Error
|
||||
- **Source:** azd
|
||||
- **Message:** Not logged in to Azure Developer CLI
|
||||
- **Remediation:** Run `azd auth login` to authenticate, then re-run preflight validation
|
||||
```
|
||||
|
||||
### Token Expired
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
AADSTS700024: Client assertion is not within its valid time range
|
||||
AADSTS50173: The provided grant has expired
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note the error
|
||||
2. Suggest re-authentication
|
||||
3. Skip Azure operations
|
||||
|
||||
---
|
||||
|
||||
## Permission Errors
|
||||
|
||||
### Insufficient RBAC Permissions
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
AuthorizationFailed: The client '...' with object id '...' does not have authorization
|
||||
to perform action '...' over scope '...'
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. **First attempt:** Retry with `--validation-level ProviderNoRbac`
|
||||
2. Note the permission limitation in the report
|
||||
3. If ProviderNoRbac also fails, report the specific missing permission
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ⚠️ Limited Permission Validation
|
||||
|
||||
- **Severity:** Warning
|
||||
- **Source:** what-if
|
||||
- **Message:** Full RBAC validation failed; using read-only validation
|
||||
- **Detail:** Missing permission: `Microsoft.Resources/deployments/write` on scope `/subscriptions/xxx`
|
||||
- **Recommendation:** Request Contributor role on the target resource group, or verify deployment permissions with your administrator
|
||||
```
|
||||
|
||||
### Resource Group Not Found
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
ResourceGroupNotFound: Resource group 'xxx' could not be found.
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note in report
|
||||
2. Suggest creating the resource group
|
||||
3. Skip what-if for this scope
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ❌ Resource Group Does Not Exist
|
||||
|
||||
- **Severity:** Error
|
||||
- **Source:** what-if
|
||||
- **Message:** Resource group 'my-rg' does not exist
|
||||
- **Remediation:** Create the resource group before deployment:
|
||||
```bash
|
||||
az group create --name my-rg --location eastus
|
||||
```
|
||||
```
|
||||
|
||||
### Subscription Access Denied
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
SubscriptionNotFound: The subscription 'xxx' could not be found.
|
||||
InvalidSubscriptionId: Subscription '...' is not valid
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note in report
|
||||
2. Suggest checking subscription ID
|
||||
3. List available subscriptions
|
||||
|
||||
---
|
||||
|
||||
## Bicep Syntax Errors
|
||||
|
||||
### Compilation Errors
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
/path/main.bicep(22,51) : Error BCP064: Found unexpected tokens
|
||||
/path/main.bicep(10,5) : Error BCP018: Expected the "=" character at this location
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Parse error output for line/column numbers
|
||||
2. Include all errors in report (don't stop at first)
|
||||
3. Continue to what-if (may provide additional context)
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ❌ Bicep Syntax Error
|
||||
|
||||
- **Severity:** Error
|
||||
- **Source:** bicep build
|
||||
- **Location:** `main.bicep:22:51`
|
||||
- **Code:** BCP064
|
||||
- **Message:** Found unexpected tokens in interpolated expression
|
||||
- **Remediation:** Check the string interpolation syntax at line 22
|
||||
- **Documentation:** https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/diagnostics/bcp064
|
||||
```
|
||||
|
||||
### Module Not Found
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
Error BCP091: An error occurred reading file. Could not find file '...'
|
||||
Error BCP190: The module is not valid
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note missing module
|
||||
2. Check if `bicep restore` is needed
|
||||
3. Verify module path
|
||||
|
||||
### Parameter File Issues
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
Error BCP032: The value must be a compile-time constant
|
||||
Error BCP035: The specified object is missing required properties
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note parameter issues
|
||||
2. Indicate which parameters are problematic
|
||||
3. Suggest fixes
|
||||
|
||||
---
|
||||
|
||||
## Tool Not Installed
|
||||
|
||||
### Azure CLI Not Found
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
'az' is not recognized as an internal or external command
|
||||
az: command not found
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note in report
|
||||
2. Provide installation instructions.
|
||||
- If available use the Azure MCP `extension_cli_install` tool to get installation instructions.
|
||||
- Otherwise look for instructions at https://learn.microsoft.com/en-us/cli/azure/install-azure-cli.
|
||||
3. Skip az commands
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ⏭️ Azure CLI Not Installed
|
||||
|
||||
- **Severity:** Warning
|
||||
- **Source:** environment
|
||||
- **Message:** Azure CLI (az) is not installed or not in PATH
|
||||
- **Remediation:** Install the Azure CLI <ADD INSTALLATION INSTRUCTIONS HERE>
|
||||
- **Impact:** What-if validation using az commands was skipped
|
||||
```
|
||||
|
||||
### Bicep CLI Not Found
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
'bicep' is not recognized as an internal or external command
|
||||
bicep: command not found
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note in report
|
||||
2. Azure CLI may have built-in Bicep - try `az bicep build`
|
||||
3. Provide installation link
|
||||
|
||||
**Report Entry:**
|
||||
```markdown
|
||||
#### ⏭️ Bicep CLI Not Installed
|
||||
|
||||
- **Severity:** Warning
|
||||
- **Source:** environment
|
||||
- **Message:** Bicep CLI is not installed
|
||||
- **Remediation:** Install Bicep CLI: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install
|
||||
- **Impact:** Syntax validation was skipped; Azure will validate during what-if
|
||||
```
|
||||
|
||||
### Azure Developer CLI Not Found
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
'azd' is not recognized as an internal or external command
|
||||
azd: command not found
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. If `azure.yaml` exists, this is required
|
||||
2. Fall back to az CLI commands if possible
|
||||
3. Note in report
|
||||
|
||||
---
|
||||
|
||||
## What-If Specific Errors
|
||||
|
||||
### Nested Template Limits
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
The deployment exceeded the nested template limit of 500
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note as warning (not error)
|
||||
2. Explain affected resources show as "Ignore"
|
||||
3. Suggest manual review
|
||||
|
||||
### Template Link Not Supported
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
templateLink references in nested deployments won't be visible in what-if
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note as warning
|
||||
2. Explain limitation
|
||||
3. Resources will be verified during actual deployment
|
||||
|
||||
### Unevaluated Expressions
|
||||
|
||||
**Detection:** Properties showing function names like `[utcNow()]` instead of values
|
||||
|
||||
**Handling:**
|
||||
1. Note as informational
|
||||
2. Explain these are evaluated at deployment time
|
||||
3. Not an error
|
||||
|
||||
---
|
||||
|
||||
## Network Errors
|
||||
|
||||
### Timeout
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
Connection timed out
|
||||
Request timed out
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Suggest retry
|
||||
2. Check network connectivity
|
||||
3. May indicate Azure service issues
|
||||
|
||||
### SSL/TLS Errors
|
||||
|
||||
**Detection:**
|
||||
```
|
||||
SSL: CERTIFICATE_VERIFY_FAILED
|
||||
unable to get local issuer certificate
|
||||
```
|
||||
|
||||
**Handling:**
|
||||
1. Note in report
|
||||
2. May indicate proxy or corporate firewall
|
||||
3. Suggest checking SSL settings
|
||||
|
||||
---
|
||||
|
||||
## Fallback Strategy
|
||||
|
||||
When primary validation fails, attempt fallbacks in order:
|
||||
|
||||
```
|
||||
Provider (full RBAC validation)
|
||||
↓ fails with permission error
|
||||
ProviderNoRbac (validation without write permission check)
|
||||
↓ fails
|
||||
Template (static syntax only)
|
||||
↓ fails
|
||||
Report all failures and skip what-if analysis
|
||||
```
|
||||
|
||||
**Always continue to generate the report**, even if all validation steps fail.
|
||||
|
||||
---
|
||||
|
||||
## Error Report Aggregation
|
||||
|
||||
When multiple errors occur, aggregate them logically:
|
||||
|
||||
1. **Group by source** (bicep, what-if, permissions)
|
||||
2. **Order by severity** (errors before warnings)
|
||||
3. **Deduplicate** similar errors
|
||||
4. **Provide summary count** at the top
|
||||
|
||||
Example:
|
||||
```markdown
|
||||
## Issues
|
||||
|
||||
Found **3 errors** and **2 warnings**
|
||||
|
||||
### Errors (3)
|
||||
|
||||
1. [Bicep Syntax Error - main.bicep:22:51](#error-1)
|
||||
2. [Bicep Syntax Error - main.bicep:45:10](#error-2)
|
||||
3. [Resource Group Not Found](#error-3)
|
||||
|
||||
### Warnings (2)
|
||||
|
||||
1. [Limited Permission Validation](#warning-1)
|
||||
2. [Nested Template Limit Reached](#warning-2)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Code Reference
|
||||
|
||||
| Tool | Exit Code | Meaning |
|
||||
|------|-----------|---------|
|
||||
| az | 0 | Success |
|
||||
| az | 1 | General error |
|
||||
| az | 2 | Command not found |
|
||||
| az | 3 | Required argument missing |
|
||||
| azd | 0 | Success |
|
||||
| azd | 1 | Error |
|
||||
| bicep | 0 | Build succeeded |
|
||||
| bicep | 1 | Build failed (errors) |
|
||||
| bicep | 2 | Build succeeded with warnings |
|
||||
352
skills/azure-deployment-preflight/references/REPORT-TEMPLATE.md
Normal file
352
skills/azure-deployment-preflight/references/REPORT-TEMPLATE.md
Normal file
@@ -0,0 +1,352 @@
|
||||
# Preflight Report Template
|
||||
|
||||
Use this template structure when generating `preflight-report.md` in the project root.
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# Azure Deployment Preflight Report
|
||||
|
||||
**Generated:** {timestamp}
|
||||
**Status:** {overall-status}
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Template File(s)** | {bicep-files} |
|
||||
| **Parameter File(s)** | {param-files-or-none} |
|
||||
| **Project Type** | {azd-project | standalone-bicep} |
|
||||
| **Deployment Scope** | {resourceGroup | subscription | managementGroup | tenant} |
|
||||
| **Target** | {resource-group-name | subscription-name | mg-id} |
|
||||
| **Validation Level** | {Provider | ProviderNoRbac} |
|
||||
|
||||
### Validation Results
|
||||
|
||||
| Check | Status | Details |
|
||||
|-------|--------|---------|
|
||||
| Bicep Syntax | {✅ Pass | ❌ Fail | ⚠️ Warnings | ⏭️ Skipped} | {details} |
|
||||
| What-If Analysis | {✅ Pass | ❌ Fail | ⏭️ Skipped} | {details} |
|
||||
| Permission Check | {✅ Pass | ⚠️ Limited | ❌ Fail} | {details} |
|
||||
|
||||
---
|
||||
|
||||
## Tools Executed
|
||||
|
||||
### Commands Run
|
||||
|
||||
| Step | Command | Exit Code | Duration |
|
||||
|------|---------|-----------|----------|
|
||||
| 1 | `{command}` | {0 | non-zero} | {duration} |
|
||||
| 2 | `{command}` | {0 | non-zero} | {duration} |
|
||||
|
||||
### Tool Versions
|
||||
|
||||
| Tool | Version |
|
||||
|------|---------|
|
||||
| Azure CLI | {version} |
|
||||
| Bicep CLI | {version} |
|
||||
| Azure Developer CLI | {version-or-n/a} |
|
||||
|
||||
---
|
||||
|
||||
## Issues
|
||||
|
||||
{if-no-issues}
|
||||
✅ **No issues found.** The deployment is ready to proceed.
|
||||
{end-if}
|
||||
|
||||
{if-issues-exist}
|
||||
### Errors
|
||||
|
||||
{for-each-error}
|
||||
#### ❌ {error-title}
|
||||
|
||||
- **Severity:** Error
|
||||
- **Source:** {bicep-build | what-if | permissions}
|
||||
- **Location:** {file-path}:{line}:{column} (if applicable)
|
||||
- **Message:** {error-message}
|
||||
- **Remediation:** {suggested-fix}
|
||||
- **Documentation:** {link-if-available}
|
||||
|
||||
{end-for-each}
|
||||
|
||||
### Warnings
|
||||
|
||||
{for-each-warning}
|
||||
#### ⚠️ {warning-title}
|
||||
|
||||
- **Severity:** Warning
|
||||
- **Source:** {source}
|
||||
- **Message:** {warning-message}
|
||||
- **Recommendation:** {suggested-action}
|
||||
|
||||
{end-for-each}
|
||||
{end-if}
|
||||
|
||||
---
|
||||
|
||||
## What-If Results
|
||||
|
||||
{if-what-if-succeeded}
|
||||
|
||||
### Change Summary
|
||||
|
||||
| Change Type | Count |
|
||||
|-------------|-------|
|
||||
| 🆕 Create | {count} |
|
||||
| 📝 Modify | {count} |
|
||||
| 🗑️ Delete | {count} |
|
||||
| ✓ No Change | {count} |
|
||||
| ⚠️ Ignore | {count} |
|
||||
|
||||
### Resources to Create
|
||||
|
||||
{if-resources-to-create}
|
||||
| Resource Type | Resource Name |
|
||||
|---------------|---------------|
|
||||
| {type} | {name} |
|
||||
{end-if}
|
||||
|
||||
{if-no-resources-to-create}
|
||||
*No resources will be created.*
|
||||
{end-if}
|
||||
|
||||
### Resources to Modify
|
||||
|
||||
{if-resources-to-modify}
|
||||
#### {resource-type}/{resource-name}
|
||||
|
||||
| Property | Current Value | New Value |
|
||||
|----------|---------------|-----------|
|
||||
| {property-path} | {current} | {new} |
|
||||
|
||||
{end-if}
|
||||
|
||||
{if-no-resources-to-modify}
|
||||
*No resources will be modified.*
|
||||
{end-if}
|
||||
|
||||
### Resources to Delete
|
||||
|
||||
{if-resources-to-delete}
|
||||
| Resource Type | Resource Name |
|
||||
|---------------|---------------|
|
||||
| {type} | {name} |
|
||||
|
||||
> ⚠️ **Warning:** Resources listed for deletion will be permanently removed.
|
||||
{end-if}
|
||||
|
||||
{if-no-resources-to-delete}
|
||||
*No resources will be deleted.*
|
||||
{end-if}
|
||||
|
||||
{end-if-what-if-succeeded}
|
||||
|
||||
{if-what-if-failed}
|
||||
### What-If Analysis Failed
|
||||
|
||||
The what-if operation could not complete. See the Issues section for details.
|
||||
{end-if}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
{generate-based-on-findings}
|
||||
|
||||
1. {recommendation-1}
|
||||
2. {recommendation-2}
|
||||
3. {recommendation-3}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
{if-all-passed}
|
||||
The preflight validation passed. You can proceed with deployment:
|
||||
|
||||
**For azd projects:**
|
||||
```bash
|
||||
azd provision
|
||||
# or
|
||||
azd up
|
||||
```
|
||||
|
||||
**For standalone Bicep:**
|
||||
```bash
|
||||
az deployment group create \
|
||||
--resource-group {rg-name} \
|
||||
--template-file {bicep-file} \
|
||||
--parameters {param-file}
|
||||
```
|
||||
{end-if}
|
||||
|
||||
{if-issues-exist}
|
||||
Please resolve the issues listed above before deploying. After fixes:
|
||||
|
||||
1. Re-run preflight validation to verify fixes
|
||||
2. Proceed with deployment once all checks pass
|
||||
{end-if}
|
||||
|
||||
---
|
||||
|
||||
*Report generated by Azure Deployment Preflight Skill*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Status Values
|
||||
|
||||
### Overall Status
|
||||
|
||||
| Status | Meaning | Visual |
|
||||
|--------|---------|--------|
|
||||
| **Pass** | All checks succeeded, safe to deploy | ✅ |
|
||||
| **Pass with Warnings** | Checks succeeded but review warnings | ⚠️ |
|
||||
| **Fail** | One or more checks failed | ❌ |
|
||||
|
||||
### Individual Check Status
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| ✅ Pass | Check completed successfully |
|
||||
| ❌ Fail | Check found errors |
|
||||
| ⚠️ Warnings | Check passed with warnings |
|
||||
| ⏭️ Skipped | Check was skipped (tool unavailable, etc.) |
|
||||
|
||||
---
|
||||
|
||||
## Example Report
|
||||
|
||||
```markdown
|
||||
# Azure Deployment Preflight Report
|
||||
|
||||
**Generated:** 2026-01-16T14:32:00Z
|
||||
**Status:** ⚠️ Pass with Warnings
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Template File(s)** | `infra/main.bicep` |
|
||||
| **Parameter File(s)** | `infra/main.bicepparam` |
|
||||
| **Project Type** | azd project |
|
||||
| **Deployment Scope** | subscription |
|
||||
| **Target** | my-subscription |
|
||||
| **Validation Level** | Provider |
|
||||
|
||||
### Validation Results
|
||||
|
||||
| Check | Status | Details |
|
||||
|-------|--------|---------|
|
||||
| Bicep Syntax | ✅ Pass | No errors found |
|
||||
| What-If Analysis | ⚠️ Warnings | 1 resource ignored due to nested template limits |
|
||||
| Permission Check | ✅ Pass | Full deployment permissions verified |
|
||||
|
||||
---
|
||||
|
||||
## Tools Executed
|
||||
|
||||
### Commands Run
|
||||
|
||||
| Step | Command | Exit Code | Duration |
|
||||
|------|---------|-----------|----------|
|
||||
| 1 | `bicep build infra/main.bicep --stdout` | 0 | 1.2s |
|
||||
| 2 | `azd provision --preview --environment dev` | 0 | 8.4s |
|
||||
|
||||
### Tool Versions
|
||||
|
||||
| Tool | Version |
|
||||
|------|---------|
|
||||
| Azure CLI | 2.76.0 |
|
||||
| Bicep CLI | 0.25.3 |
|
||||
| Azure Developer CLI | 1.9.0 |
|
||||
|
||||
---
|
||||
|
||||
## Issues
|
||||
|
||||
### Warnings
|
||||
|
||||
#### ⚠️ Nested Template Limit Reached
|
||||
|
||||
- **Severity:** Warning
|
||||
- **Source:** what-if
|
||||
- **Message:** 1 resource was ignored because nested template expansion limits were reached
|
||||
- **Recommendation:** Review the ignored resource manually after deployment
|
||||
|
||||
---
|
||||
|
||||
## What-If Results
|
||||
|
||||
### Change Summary
|
||||
|
||||
| Change Type | Count |
|
||||
|-------------|-------|
|
||||
| 🆕 Create | 3 |
|
||||
| 📝 Modify | 1 |
|
||||
| 🗑️ Delete | 0 |
|
||||
| ✓ No Change | 2 |
|
||||
| ⚠️ Ignore | 1 |
|
||||
|
||||
### Resources to Create
|
||||
|
||||
| Resource Type | Resource Name |
|
||||
|---------------|---------------|
|
||||
| Microsoft.Resources/resourceGroups | rg-myapp-dev |
|
||||
| Microsoft.Storage/storageAccounts | stmyappdev |
|
||||
| Microsoft.Web/sites | app-myapp-dev |
|
||||
|
||||
### Resources to Modify
|
||||
|
||||
#### Microsoft.KeyVault/vaults/kv-myapp-dev
|
||||
|
||||
| Property | Current Value | New Value |
|
||||
|----------|---------------|-----------|
|
||||
| properties.sku.name | standard | premium |
|
||||
| tags.environment | staging | dev |
|
||||
|
||||
### Resources to Delete
|
||||
|
||||
*No resources will be deleted.*
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. Review the storage account name `stmyappdev` to ensure it meets naming requirements
|
||||
2. Confirm the Key Vault SKU upgrade from standard to premium is intentional
|
||||
3. The ignored nested template resource should be verified after deployment
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
The preflight validation passed with warnings. Review the warnings above, then proceed:
|
||||
|
||||
```bash
|
||||
azd provision --environment dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Report generated by Azure Deployment Preflight Skill*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Formatting Guidelines
|
||||
|
||||
1. **Use consistent emoji** for visual scanning
|
||||
2. **Include line numbers** when referencing Bicep errors
|
||||
3. **Provide actionable remediation** for each issue
|
||||
4. **Link to documentation** when available
|
||||
5. **Order issues by severity** (errors first, then warnings)
|
||||
6. **Include command examples** in Next Steps
|
||||
@@ -0,0 +1,379 @@
|
||||
# Validation Commands Reference
|
||||
|
||||
This reference documents all commands used for Azure deployment preflight validation.
|
||||
|
||||
## Azure Developer CLI (azd)
|
||||
|
||||
### azd provision --preview
|
||||
|
||||
Preview infrastructure changes for azd projects without deploying.
|
||||
|
||||
```bash
|
||||
azd provision --preview [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--environment`, `-e` | Name of the environment to use |
|
||||
| `--no-prompt` | Accept defaults without prompting |
|
||||
| `--debug` | Enable debug logging |
|
||||
| `--cwd` | Set working directory |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Preview with default environment
|
||||
azd provision --preview
|
||||
|
||||
# Preview specific environment
|
||||
azd provision --preview --environment dev
|
||||
|
||||
# Preview without prompts (CI/CD)
|
||||
azd provision --preview --no-prompt
|
||||
```
|
||||
|
||||
**Output:** Shows resources that will be created, modified, or deleted.
|
||||
|
||||
### azd auth login
|
||||
|
||||
Authenticate to Azure for azd operations.
|
||||
|
||||
```bash
|
||||
azd auth login [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--check-status` | Check login status without logging in |
|
||||
| `--use-device-code` | Use device code flow |
|
||||
| `--tenant-id` | Specify tenant |
|
||||
| `--client-id` | Service principal client ID |
|
||||
|
||||
### azd env list
|
||||
|
||||
List available environments.
|
||||
|
||||
```bash
|
||||
azd env list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Azure CLI (az)
|
||||
|
||||
### az deployment group what-if
|
||||
|
||||
Preview changes for resource group deployments.
|
||||
|
||||
```bash
|
||||
az deployment group what-if \
|
||||
--resource-group <rg-name> \
|
||||
--template-file <bicep-file> \
|
||||
[options]
|
||||
```
|
||||
|
||||
**Required Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `--resource-group`, `-g` | Target resource group name |
|
||||
| `--template-file`, `-f` | Path to Bicep file |
|
||||
|
||||
**Optional Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `--parameters`, `-p` | Parameter file or inline values |
|
||||
| `--validation-level` | `Provider` (default), `ProviderNoRbac`, or `Template` |
|
||||
| `--result-format` | `FullResourcePayloads` (default) or `ResourceIdOnly` |
|
||||
| `--no-pretty-print` | Output raw JSON for parsing |
|
||||
| `--name`, `-n` | Deployment name |
|
||||
| `--exclude-change-types` | Exclude specific change types from output |
|
||||
|
||||
**Validation Levels:**
|
||||
| Level | Description | Use Case |
|
||||
|-------|-------------|----------|
|
||||
| `Provider` | Full validation with RBAC checks | Default, most thorough |
|
||||
| `ProviderNoRbac` | Full validation, read permissions only | When lacking deploy permissions |
|
||||
| `Template` | Static syntax validation only | Quick syntax check |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Basic what-if
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep
|
||||
|
||||
# With parameters and full validation
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--parameters main.bicepparam \
|
||||
--validation-level Provider
|
||||
|
||||
# Fallback without RBAC checks
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--validation-level ProviderNoRbac
|
||||
|
||||
# JSON output for parsing
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--no-pretty-print
|
||||
```
|
||||
|
||||
### az deployment sub what-if
|
||||
|
||||
Preview changes for subscription-level deployments.
|
||||
|
||||
```bash
|
||||
az deployment sub what-if \
|
||||
--location <location> \
|
||||
--template-file <bicep-file> \
|
||||
[options]
|
||||
```
|
||||
|
||||
**Required Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `--location`, `-l` | Location for deployment metadata |
|
||||
| `--template-file`, `-f` | Path to Bicep file |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
az deployment sub what-if \
|
||||
--location eastus \
|
||||
--template-file main.bicep \
|
||||
--parameters main.bicepparam \
|
||||
--validation-level Provider
|
||||
```
|
||||
|
||||
### az deployment mg what-if
|
||||
|
||||
Preview changes for management group deployments.
|
||||
|
||||
```bash
|
||||
az deployment mg what-if \
|
||||
--location <location> \
|
||||
--management-group-id <mg-id> \
|
||||
--template-file <bicep-file> \
|
||||
[options]
|
||||
```
|
||||
|
||||
**Required Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `--location`, `-l` | Location for deployment metadata |
|
||||
| `--management-group-id`, `-m` | Target management group ID |
|
||||
| `--template-file`, `-f` | Path to Bicep file |
|
||||
|
||||
### az deployment tenant what-if
|
||||
|
||||
Preview changes for tenant-level deployments.
|
||||
|
||||
```bash
|
||||
az deployment tenant what-if \
|
||||
--location <location> \
|
||||
--template-file <bicep-file> \
|
||||
[options]
|
||||
```
|
||||
|
||||
**Required Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `--location`, `-l` | Location for deployment metadata |
|
||||
| `--template-file`, `-f` | Path to Bicep file |
|
||||
|
||||
### az login
|
||||
|
||||
Authenticate to Azure CLI.
|
||||
|
||||
```bash
|
||||
az login [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--tenant`, `-t` | Tenant ID or domain |
|
||||
| `--use-device-code` | Use device code flow |
|
||||
| `--service-principal` | Login as service principal |
|
||||
|
||||
### az account show
|
||||
|
||||
Display current subscription context.
|
||||
|
||||
```bash
|
||||
az account show
|
||||
```
|
||||
|
||||
### az group exists
|
||||
|
||||
Check if resource group exists.
|
||||
|
||||
```bash
|
||||
az group exists --name <rg-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bicep CLI
|
||||
|
||||
### bicep build
|
||||
|
||||
Compile Bicep to ARM JSON and validate syntax.
|
||||
|
||||
```bash
|
||||
bicep build <bicep-file> [options]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--stdout` | Output to stdout instead of file |
|
||||
| `--outdir` | Output directory |
|
||||
| `--outfile` | Output file path |
|
||||
| `--no-restore` | Skip module restore |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Validate syntax (output to stdout, no file created)
|
||||
bicep build main.bicep --stdout > /dev/null
|
||||
|
||||
# Build to specific directory
|
||||
bicep build main.bicep --outdir ./build
|
||||
|
||||
# Validate multiple files
|
||||
for f in *.bicep; do bicep build "$f" --stdout; done
|
||||
```
|
||||
|
||||
**Error Output Format:**
|
||||
```
|
||||
/path/to/file.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
|
||||
/path/to/file.bicep(22,51) : Error BCP004: The string at this location is not terminated.
|
||||
```
|
||||
|
||||
Format: `<file>(<line>,<column>) : <severity> <code>: <message>`
|
||||
|
||||
### bicep --version
|
||||
|
||||
Check Bicep CLI version.
|
||||
|
||||
```bash
|
||||
bicep --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Parameter File Detection
|
||||
|
||||
### Bicep Parameters (.bicepparam)
|
||||
|
||||
Modern Bicep parameter files (recommended):
|
||||
|
||||
```bicep
|
||||
using './main.bicep'
|
||||
|
||||
param location = 'eastus'
|
||||
param environment = 'dev'
|
||||
param tags = {
|
||||
environment: 'dev'
|
||||
project: 'myapp'
|
||||
}
|
||||
```
|
||||
|
||||
**Detection pattern:** `<template-name>.bicepparam`
|
||||
|
||||
### JSON Parameters (.parameters.json)
|
||||
|
||||
Traditional ARM parameter files:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
|
||||
"contentVersion": "1.0.0.0",
|
||||
"parameters": {
|
||||
"location": { "value": "eastus" },
|
||||
"environment": { "value": "dev" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Detection patterns:**
|
||||
- `<template-name>.parameters.json`
|
||||
- `parameters.json`
|
||||
- `parameters/<env>.json`
|
||||
|
||||
### Using Parameters with Commands
|
||||
|
||||
```bash
|
||||
# Bicep parameters file
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--parameters main.bicepparam
|
||||
|
||||
# JSON parameters file
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--parameters @parameters.json
|
||||
|
||||
# Inline parameter overrides
|
||||
az deployment group what-if \
|
||||
--resource-group my-rg \
|
||||
--template-file main.bicep \
|
||||
--parameters main.bicepparam \
|
||||
--parameters location=westus
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Determining Deployment Scope
|
||||
|
||||
Check the Bicep file's `targetScope` declaration:
|
||||
|
||||
```bicep
|
||||
// Resource Group (default if not specified)
|
||||
targetScope = 'resourceGroup'
|
||||
|
||||
// Subscription
|
||||
targetScope = 'subscription'
|
||||
|
||||
// Management Group
|
||||
targetScope = 'managementGroup'
|
||||
|
||||
// Tenant
|
||||
targetScope = 'tenant'
|
||||
```
|
||||
|
||||
**Scope to Command Mapping:**
|
||||
|
||||
| targetScope | Command | Required Parameters |
|
||||
|-------------|---------|---------------------|
|
||||
| `resourceGroup` | `az deployment group what-if` | `--resource-group` |
|
||||
| `subscription` | `az deployment sub what-if` | `--location` |
|
||||
| `managementGroup` | `az deployment mg what-if` | `--location`, `--management-group-id` |
|
||||
| `tenant` | `az deployment tenant what-if` | `--location` |
|
||||
|
||||
---
|
||||
|
||||
## Version Requirements
|
||||
|
||||
| Tool | Minimum Version | Recommended Version | Key Features |
|
||||
|------|-----------------|---------------------|--------------|
|
||||
| Azure CLI | 2.14.0 | 2.76.0+ | `--validation-level` switch |
|
||||
| Azure Developer CLI | 1.0.0 | Latest | `--preview` flag |
|
||||
| Bicep CLI | 0.4.0 | Latest | Best error messages |
|
||||
|
||||
**Check versions:**
|
||||
```bash
|
||||
az --version
|
||||
azd version
|
||||
bicep --version
|
||||
```
|
||||
Reference in New Issue
Block a user