pulumi-arm-to-pulumi
Convert or migrate Azure ARM (Azure Resource Manager) templates, Bicep templates, or code to Pulumi, including importing existing Azure resources. This skill MUST be loaded whenever a user requests migration, conversion, or import of ARM templates, Bicep templates, ARM code, Bicep code, or Azure resources to Pulumi.
pulumi · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add pulumi/agent-skills --skill pulumi-arm-to-pulumiAbout this skill
name: pulumi-arm-to-pulumi description: Convert or migrate Azure ARM (Azure Resource Manager) templates, Bicep templates, or code to Pulumi, including importing existing Azure resources. This skill MUST be loaded whenever a user requests migration, conversion, or import of ARM templates, Bicep templates, ARM code, Bicep code, or Azure resources to Pulumi.
IMPORTANT: PLAN ADJUSTMENT REQUIRED
If you have already generated a migration plan before loading this skill, you MUST:
- Review your existing plan against the workflows and requirements in this skill
- Identify any gaps, missing steps, or incorrect assumptions
- Update and revise your plan to align with this skill's guidance
- Communicate the adjusted plan to the user before proceeding
CRITICAL SUCCESS REQUIREMENTS
The migration output MUST meet all of the following:
-
Complete Resource Coverage
- Every ARM template resource MUST:
- Be represented in the Pulumi program OR
- Be explicitly justified in the final report.
- Every ARM template resource MUST:
-
Successful Deployment
- The produced Pulumi program must be structurally valid and capable of a successful
pulumi preview(assuming proper config).
- The produced Pulumi program must be structurally valid and capable of a successful
-
Zero-Diff Import Validation (if importing existing resources)
- After import,
pulumi previewmust show:- NO updates
- NO replaces
- NO creates
- NO deletes
- Any diffs must be resolved using the Preview Resolution Workflow. See arm-import.md.
- After import,
-
Final Migration Report
- Always output a formal migration report suitable for a Pull Request.
- Include:
- ARM → Pulumi resource mapping
- Provider decisions (azure-native vs azure)
- Behavioral differences
- Missing or manually required steps
- Validation instructions
WHEN INFORMATION IS MISSING
If a user-provided ARM template is incomplete, ambiguous, or missing artifacts, ask targeted questions before generating Pulumi code.
If there is ambiguity on how to handle a specific resource property on import, ask targeted questions before altering Pulumi code.
MIGRATION WORKFLOW
Follow this workflow exactly and in this order:
1. INFORMATION GATHERING
1.1 Verify Azure Credentials
Running Azure CLI commands (e.g., az resource list, az resource show). Requires initial login using ESC and az login
- If the user has already provided an ESC environment, use it.
- If no ESC environment is specified, ask the user which ESC environment to use before proceeding with Azure CLI commands.
Setting up Azure CLI using ESC:
- ESC environments can provide Azure credentials through environment variables or Azure CLI configuration
- Login to Azure using ESC to provide credentials, e.g:
pulumi env run {org}/{project}/{environment} -- bash -c 'az login --service-principal -u "$ARM_CLIENT_ID" --tenant "$ARM_TENANT_ID" --federated-token "$ARM_OIDC_TOKEN"'. ESC is not required after establishing the session - Verify credentials are working:
az account show - Confirm subscription:
az account list --query "[].{Name:name, SubscriptionId:id, IsDefault:isDefault}" -o table
For detailed ESC information: Load the pulumi-esc skill by calling the tool "Skill" with name = "pulumi-esc"
1.2 Analyze ARM Template Structure
ARM templates do not have the concept of "stacks" like CloudFormation. Read the ARM template JSON file directly:
# View template structure
cat template.json | jq '.resources[] | {type: .type, name: .name}'
# View parameters
cat template.json | jq '.parameters'
# View variables
cat template.json | jq '.variables'
Extract:
- Resource types and names
- Parameters and their default values
- Variables and expressions
- Dependencies (dependsOn arrays)
- Nested templates or linked templates
- Copy loops (iteration constructs)
- Conditional deployments (condition property)
Documentation: ARM Template Structure
1.3 Build Resource Inventory (if importing existing resources)
If the ARM template has already been deployed and you're importing existing resources:
# List all resources in a resource group
az resource list \
--resource-group <resource-group-name> \
--output json
# Get specific resource details
az resource show \
--ids <resource-id> \
--output json
# Query specific properties using JMESPath
az resource show \
--ids <resource-id> \
--query "{name:name, location:location, properties:properties}" \
--output json
Documentation: Azure CLI Documentation
2. CODE CONVERSION (ARM → PULUMI)
IMPORTANT: ARM to Pulumi conversion requires manual translation. There is NO automated conversion tool for ARM templates. You are responsible for the complete conversion.
Key Conversion Principles
-
Provider Strategy:
- Default: Use
@pulumi/azure-nativefor full Azure Resource Manager API coverage - Fallback: Use
@pulumi/azure(classic provider) when azure-native doesn't support specific features or when you need simplified abstractions
Documentation:
- Default: Use
-
Language Support:
- TypeScript/JavaScript: Most common, excellent IDE support
- Python: Great for data teams and ML workflows
- C#: Natural fit for .NET teams
- Go: High performance, strong typing
- Java: Enterprise Java teams
- YAML: Simple declarative approach
- Choose based on user preference or existing codebase
-
Complete Coverage:
- Convert ALL resources in the ARM template
- Preserve all conditionals, loops, and dependencies
- Maintain parameter and variable logic
**Follow conversion patterns in [arm-conversion-patterns.md](arm-conversion-
Read the complete source ↗