AzConvert Tutorial — Step-by-Step Conversion Best PracticesConverting infrastructure, templates, or configurations for Microsoft Azure can be complex. AzConvert is a tool designed to simplify conversions between formats, update resource definitions for newer API versions, and help migrate templates or configurations into Azure Resource Manager (ARM) or Bicep formats. This tutorial covers practical, step-by-step best practices for using AzConvert effectively and safely: planning, preparing inputs, running conversions, validating outputs, and applying results in production.
What AzConvert does (short overview)
AzConvert automates transformation of Azure artifacts — for example:
- converting classic Azure Service Manager (ASM) templates to ARM templates,
- translating ARM JSON templates to Bicep,
- updating templates to use newer API versions or resource provider namespaces,
- refactoring parameterization, naming, and dependency declarations.
Use AzConvert when you need to speed up repetitive conversion tasks and reduce manual errors.
1. Plan before converting
Converting blindly risks breaking deployments. Start with planning:
- Inventory: list templates, scripts, and resources to convert (ARM JSON, ASM, Terraform, CLI scripts, etc.).
- Goals: decide target format (ARM JSON, Bicep, Terraform HCL) and conventions (naming, tagging, regions).
- Scope: choose whether to convert everything at once or in smaller, testable batches.
- Stakeholders: notify teams that own the resources—conversion may change deployment behavior or require approvals.
- Backup: store original artifacts in version control and create deployment snapshots or resource group exports.
2. Prepare inputs
Properly structured inputs improve conversion success.
- Clean templates: remove unused resources and parameters, resolve hard-coded values where appropriate, and document assumptions.
- Use consistent resource names and parameter types to help the converter map types correctly.
- For scripts, separate discovery (gathering resource metadata) from creation logic where possible.
- For Terraform or other non-ARM artifacts, generate a clear resource inventory to guide conversion decisions.
Example pre-conversion checklist:
- All ARM templates validate with az deployment group validate.
- Parameter files are present and documented.
- Secrets and credentials are moved to Key Vault or parameterized (do not hard-code).
3. Run AzConvert — common modes and flags
AzConvert typically offers modes for different source/target pairs and flags for customization. The exact CLI syntax depends on the version you use; here are common modes and recommended flags to look for:
-
Modes:
- asm-to-arm (classic to ARM)
- arm-to-bicep (ARM JSON to Bicep)
- arm-api-update (update resource apiVersions and namespaces)
- terraform-to-arm or terraform-to-bicep (if supported)
-
Useful flags (examples):
- –input / -i : input file or folder
- –output / -o : output path
- –dry-run : simulate conversion without writing files
- –api-map : provide custom mapping for provider namespaces or versions
- –preserve-comments : retain original comments where possible
- –force : overwrite files (use cautiously)
- –verbose : detailed logs
Run a dry run first:
azconvert --mode arm-to-bicep -i ./templates -o ./out --dry-run --verbose Dry-run reveals warnings and changes without modifying files.
4. Review and adjust converted outputs
Automated converters can’t perfectly match human intent. Always review outputs.
- Syntax & style: ensure generated Bicep or ARM follows your organization’s style (naming conventions, parameter placement).
- Parameterization: check whether values that should be parameters were left inline; extract them if needed.
- Dependencies: verify resource dependencies (dependsOn in ARM or implicit ordering in Bicep) remain correct.
- API versions: confirm conversion chose appropriate apiVersions for your target subscription/region.
- Resource provider changes: some resources may have moved namespaces (example: classic compute networks → network provider) — ensure mapping is correct.
- Modularization: consider refactoring large templates into smaller modules (Bicep modules or linked ARM templates).
Example adjustments:
- Convert inline storage account names into parameters with validation.
- Extract SKU or size values into parameters with allowed values.
- Replace hard-coded locations with a single location parameter.
5. Validate converted templates
Validation is essential before deploying.
- Local validation:
- For ARM JSON: az deployment group validate –template-file ./template.json –parameters @params.json
- For Bicep: bicep build ./main.bicep (to produce ARM JSON), then validate the ARM output.
- Linting: use linters (bicep-lint, arm-ttk) to catch best-practice issues and accessibility/security recommendations.
- Unit tests: create small test deployments in disposable resource groups or subscription sandboxes.
- Schema & API checks: verify that apiVersions used are supported in the intended Azure environment (public, government clouds).
Example:
bicep build main.bicep az deployment group validate --resource-group rg-test --template-file main.json --parameters @params.json 6. Deploy safely: staged rollout
Use progressive deployment strategies.
- Test environment: deploy to dev/test subscriptions or resource groups first.
- Canary deployment: deploy a subset of resources or workloads to validate behavior.
- Blue/Green or feature-flag deployments: for applications, keep previous version available while testing the new deployment.
- Use deployment scripts that include a rollback plan (delete or redeploy previous template).
- Monitor costs and resource usage after deployment—conversion can change SKUs or networking that affect billing.
7. Post-deployment checks and hardening
After successful deployment, perform checks and hardening:
- Access control: confirm Role-Based Access Control (RBAC) assignments and Managed Identities are preserved or re-applied.
- Secrets: verify Key Vault integration and that secrets are not present in code or parameter files.
- Tagging: apply or validate tags for billing, environment, and compliance.
- Policies: ensure Azure Policy compliance for resource types, locations, and SKUs.
- Backups: enable backup/replication resources where necessary.
8. Common pitfalls and how to avoid them
- Broken dependencies: ensure dependsOn and module references are preserved or fixed.
- Unsupported apiVersions: map to supported API versions for target subscription/region.
- Hard-coded sensitive values: always parameterize secrets and credentials.
- Naming collisions: confirm resource names remain unique across conversions and deployments.
- Overwriting production: never run conversions with –force directly against production files without review and backup.
9. Best-practice checklist (concise)
- Inventory resources and create backups.
- Run conversions in small batches.
- Always dry-run first.
- Manually review generated templates.
- Lint and validate outputs before deploying.
- Deploy to test environments, then stage to production.
- Verify RBAC, Key Vault, tags, and policies after deployment.
10. Example workflow (condensed)
- git clone repo containing ARM templates.
- Run az convert in dry-run mode:
azconvert --mode arm-to-bicep -i ./templates -o ./converted --dry-run - Review converted Bicep files; extract parameters and modularize.
- bicep build main.bicep -> main.json
- az deployment group validate –resource-group rg-test –template-file main.json –parameters @params.json
- Deploy to rg-test, run integration tests.
- After validation, deploy to staging, run perf tests.
- Promote to production with rollout strategy and monitoring.
11. When to avoid automated conversion
- Highly customized templates with hand-crafted logic and complex nested deployments.
- When organizational policy requires hand-reviewed resource definitions.
- For sensitive environments where even minor changes must be vetted.
12. Tools that complement AzConvert
- Azure CLI (az) — validation and deployments.
- Azure Resource Explorer — inspect deployed resources and provider versions.
- Bicep CLI and bicep-lint — authoring and linting Bicep.
- ARM TTK (Template Toolkit) — test templates against best practices.
- Terraform tools — if moving from or to Terraform, use state import/export helpers.
13. Final notes
AzConvert can greatly speed migrations and format transitions, but it is not a substitute for planning, review, and staged deployments. Treat converted files as first drafts: validate, test, and refine them until they meet your operational and security standards.
Leave a Reply