Pulumi Arm To Pulumi

IMPORTANT: PLAN ADJUSTMENT REQUIRED

If you have already generated a migration plan before loading this skill, you MUST:

1. Review your existing plan against the workflows and requirements in this skill 2. Identify any gaps, missing steps, or incorrect assumptions 3. Update and revise your plan to align with this skill's guidance 4. Communicate the adjusted plan to the user before proceeding

CRITICAL SUCCESS REQUIREMENTS

The migration output MUST meet all of the following:

1. Complete Resource Coverage

• Every ARM template resource MUST:
• Be represented in the Pulumi program OR
• Be explicitly justified in the final report.

2. Successful Deployment

• The produced Pulumi program must be structurally valid and capable of a successful pulumi preview (assuming proper config).

3. Zero-Diff Import Validation (if importing existing resources)

• After import, pulumi preview must show:
• NO updates
• NO replaces
• NO creates
• NO deletes
• Any diffs must be resolved using the Preview Resolution Workflow. See arm-import.md.

4. 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

1. Provider Strategy:

• Default: Use @pulumi/azure-native for 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:

• Azure Native Provider
• Azure Classic Provider

2. 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

3. 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-patterns.md).

arm-conversion-patterns.md provides:

• Parameters, variables, and outputs mapping
• Copy loops, conditionals, and dependsOn translation
• Nested templates → ComponentResource
• Azure Classic provider examples (VNet, App Service)
• TypeScript output handling and common pitfalls

3. RESOURCE IMPORT (EXISTING RESOURCES) - OPTIONAL

After conversion, you can optionally import existing resources to be managed by Pulumi. If the user does not request this, suggest it as a follow-up step to conversion.

CRITICAL: When the user requests importing existing Azure resources into Pulumi, see arm-import.md for detailed import procedures and zero-diff validation workflows.

arm-import.md provides:

• Inline import ID patterns and examples
• Azure Resource ID format conventions
• Child resource handling (e.g., WebAppApplicationSettings)
• Preview Resolution Workflow for achieving zero-diff after import
• Step-by-step debugging for property conflicts

Key Import Principles

1. Inline Import Approach:

• Use import resource option with Azure Resource IDs
• No separate import tool (unlike pulumi-cdk-importer)

2. Azure Resource IDs:

• Follow predictable pattern: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
• Can be generated by convention or queried via Azure CLI

3. Zero-Diff Validation:

• Run pulumi preview after import
• Resolve all diffs using Preview Resolution Workflow
• Goal: NO updates, replaces, creates, or deletes

4. PULUMI CONFIGURATION

Set up stack configuration matching ARM template parameters:

# Set Azure region
pulumi config set azure-native:location eastus --stack dev

# Set application parameters
pulumi config set storageAccountName mystorageaccount --stack dev

# Set secret parameters
pulumi config set --secret adminPassword MyS3cr3tP@ssw0rd --stack dev

5. VALIDATION

After achieving zero diff in preview (if importing), validate the migration:

1. Review all exports:

   pulumi stack output

2. Verify resource relationships:

   pulumi stack graph

3. Test application functionality (if applicable)

4. Document any manual steps required post-migration

WORKING WITH THE USER

If the user asks for help planning or performing an ARM to Pulumi migration, use the information above to guide the user through the conversion and import process.

FOR DETAILED DOCUMENTATION

When the user wants additional information, use the web-fetch tool to get content from the official Pulumi documentation:

• ARM Migration Guide: https://www.pulumi.com/docs/iac/adopting-pulumi/migrating-to-pulumi/from-arm/
• Azure Native Provider: https://www.pulumi.com/registry/packages/azure-native/
• Azure Classic Provider: https://www.pulumi.com/registry/packages/azure/

Microsoft Azure Documentation:

• ARM Template Reference: https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/
• Azure CLI Reference: https://learn.microsoft.com/en-us/cli/azure/
• Azure Resource IDs: https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource

OUTPUT FORMAT (REQUIRED)

When performing a migration, always produce:

1. Overview (high-level description) 2. Migration Plan Summary

• ARM template resources identified
• Conversion strategy (language, providers)
• Import approach (if applicable)

3. Pulumi Code Outputs (organized by file)

• Main program file
• Component resources (if any)
• Configuration instructions

4. Resource Mapping Table (ARM → Pulumi)

• ARM resource type → Pulumi resource type
• ARM resource name → Pulumi logical name
• Import ID (if importing)

5. Preview Resolution Notes (if importing)

• Diffs encountered
• Resolution strategy applied
• Properties ignored vs. added

6. Final Migration Report (PR-ready)

• Summary of changes
• Testing instructions
• Known limitations
• Next steps

7. Configuration Setup

• Required config values
• Example pulumi config set commands

Keep code syntactically valid and clearly separated by files.

ARM → Pulumi Conversion Patterns

Reference guide for translating ARM template constructs to Pulumi TypeScript. Covers all common patterns plus Azure Classic provider examples.

Basic Resource Conversion

ARM Template:

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2023-01-01",
  "name": "[parameters('storageAccountName')]",
  "location": "[parameters('location')]",
  "sku": {
    "name": "Standard_LRS"
  },
  "kind": "StorageV2",
  "properties": {
    "supportsHttpsTrafficOnly": true
  }
}

Pulumi TypeScript:

import * as pulumi from "@pulumi/pulumi";
import * as azure_native from "@pulumi/azure-native";

const config = new pulumi.Config();
const storageAccountName = config.require("storageAccountName");
const location = config.require("location");
const resourceGroupName = config.require("resourceGroupName");

const storageAccount = new azure_native.storage.StorageAccount("storageAccount", {
    accountName: storageAccountName,
    location: location,
    resourceGroupName: resourceGroupName,
    sku: {
        name: azure_native.storage.SkuName.Standard_LRS,
    },
    kind: azure_native.storage.Kind.StorageV2,
    enableHttpsTrafficOnly: true,
});

ARM Parameters → Pulumi Config

ARM Template:

{
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "eastus",
      "metadata": {
        "description": "Location for resources"
      }
    },
    "instanceCount": {
      "type": "int",
      "defaultValue": 2,
      "minValue": 1,
      "maxValue": 10
    },
    "enableBackup": {
      "type": "bool",
      "defaultValue": true
    },
    "secretValue": {
      "type": "securestring"
    }
  }
}

Pulumi TypeScript:

const config = new pulumi.Config();
const location = config.get("location") || "eastus";
const instanceCount = config.getNumber("instanceCount") || 2;
const enableBackup = config.getBoolean("enableBackup") ?? true;
const secretValue = config.requireSecret("secretValue"); // Returns Output<string>

ARM Variables → Pulumi Variables

ARM Template:

{
  "variables": {
    "storageAccountName": "[concat('storage', uniqueString(resourceGroup().id))]",
    "webAppName": "[concat(parameters('prefix'), '-webapp')]"
  }
}

Pulumi TypeScript:

import * as pulumi from "@pulumi/pulumi";

const config = new pulumi.Config();
const prefix = config.require("prefix");
const resourceGroupId = config.require("resourceGroupId");

// Simple variable
const webAppName = `${prefix}-webapp`;

// ARM's uniqueString() produces a deterministic 13-char hash — use a fixed suffix
// from config or a truncated ID as an approximation:
// const storageAccountName = `storage${resourceGroupId.substring(0, 8)}`.toLowerCase();
// Note: not cryptographically equivalent to ARM's uniqueString()
const storageAccountName = `storage${resourceGroupId}`.toLowerCase();

ARM Copy Loops → Pulumi Loops

ARM Template:

{
  "type": "Microsoft.Network/virtualNetworks/subnets",
  "apiVersion": "2023-05-01",
  "name": "[concat(variables('vnetName'), '/subnet-', copyIndex())]",
  "copy": {
    "name": "subnetCopy",
    "count": "[parameters('subnetCount')]"
  },
  "properties": {
    "addressPrefix": "[concat('10.0.', copyIndex(), '.0/24')]"
  }
}

Pulumi TypeScript:

const config = new pulumi.Config();
const subnetCount = config.getNumber("subnetCount") || 3;

const subnets: azure_native.network.Subnet[] = [];
for (let i = 0; i < subnetCount; i++) {
    subnets.push(new azure_native.network.Subnet(`subnet-${i}`, {
        subnetName: `subnet-${i}`,
        virtualNetworkName: vnet.name,
        resourceGroupName: resourceGroup.name,
        addressPrefix: `10.0.${i}.0/24`,
    }));
}

ARM Conditional Resources → Pulumi Conditionals

ARM Template:

{
  "type": "Microsoft.Network/publicIPAddresses",
  "apiVersion": "2023-05-01",
  "condition": "[parameters('createPublicIP')]",
  "name": "[variables('publicIPName')]",
  "location": "[parameters('location')]"
}

Pulumi TypeScript:

const config = new pulumi.Config();
const createPublicIP = config.getBoolean("createPublicIP") ?? false;

let publicIP: azure_native.network.PublicIPAddress | undefined;
if (createPublicIP) {
    publicIP = new azure_native.network.PublicIPAddress("publicIP", {
        publicIpAddressName: publicIPName,
        location: location,
        resourceGroupName: resourceGroup.name,
    });
}

// Handle optional references
const publicIPId = publicIP ? publicIP.id : pulumi.output(undefined);

ARM DependsOn → Pulumi Dependencies

ARM Template:

{
  "type": "Microsoft.Web/sites",
  "apiVersion": "2023-01-01",
  "name": "[variables('webAppName')]",
  "dependsOn": [
    "[resourceId('Microsoft.Web/serverfarms', variables('appServicePlanName'))]"
  ]
}

Pulumi TypeScript:

// Implicit dependency (preferred)
const webApp = new azure_native.web.WebApp("webApp", {
    name: webAppName,
    resourceGroupName: resourceGroup.name,
    serverFarmId: appServicePlan.id, // Implicit dependency through property reference
});

// Explicit dependency (when needed)
const webApp = new azure_native.web.WebApp("webApp", {
    name: webAppName,
    resourceGroupName: resourceGroup.name,
    serverFarmId: appServicePlan.id,
}, {
    dependsOn: [appServicePlan], // Explicit dependency
});

Nested Templates → Pulumi Component Resources

ARM Template:

{
  "type": "Microsoft.Resources/deployments",
  "apiVersion": "2021-04-01",
  "name": "nestedTemplate",
  "properties": {
    "mode": "Incremental",
    "template": {
      "resources": [...]
    }
  }
}

Pulumi Approach:

Instead of nested templates, use Pulumi ComponentResource to group related resources:

class NetworkComponent extends pulumi.ComponentResource {
    public readonly vnet: azure_native.network.VirtualNetwork;
    public readonly subnets: azure_native.network.Subnet[];

    constructor(name: string, args: NetworkComponentArgs, opts?: pulumi.ComponentResourceOptions) {
        super("custom:azure:NetworkComponent", name, {}, opts);

        const defaultOptions = { parent: this };

        this.vnet = new azure_native.network.VirtualNetwork(`${name}-vnet`, {
            virtualNetworkName: args.vnetName,
            resourceGroupName: args.resourceGroupName,
            location: args.location,
            addressSpace: {
                addressPrefixes: [args.addressPrefix],
            },
        }, defaultOptions);

        this.subnets = args.subnets.map((subnet, i) =>
            new azure_native.network.Subnet(`${name}-subnet-${i}`, {
                subnetName: subnet.name,
                virtualNetworkName: this.vnet.name,
                resourceGroupName: args.resourceGroupName,
                addressPrefix: subnet.addressPrefix,
            }, defaultOptions)
        );

        this.registerOutputs({
            vnetId: this.vnet.id,
            subnetIds: this.subnets.map(s => s.id),
        });
    }
}

ARM Outputs → Pulumi Exports

ARM Template:

{
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    },
    "storageAccountId": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
    }
  }
}

Pulumi TypeScript:

export const storageAccountName = storageAccount.name;
export const storageAccountId = storageAccount.id;

Azure Classic Provider Examples

Use @pulumi/azure (classic) when azure-native doesn't support a feature or when simplified abstractions are preferred.

Virtual Network with Classic Provider

ARM Template:

{
  "type": "Microsoft.Network/virtualNetworks",
  "apiVersion": "2023-05-01",
  "name": "[parameters('vnetName')]",
  "location": "[parameters('location')]",
  "properties": {
    "addressSpace": {
      "addressPrefixes": ["10.0.0.0/16"]
    },
    "subnets": [
      { "name": "default", "properties": { "addressPrefix": "10.0.1.0/24" } },
      { "name": "apps",    "properties": { "addressPrefix": "10.0.2.0/24" } }
    ]
  }
}

Pulumi TypeScript (Classic Provider):

import * as pulumi from "@pulumi/pulumi";
import * as azure from "@pulumi/azure";

const config = new pulumi.Config();
const vnetName = config.require("vnetName");
const location = config.require("location");
const resourceGroupName = config.require("resourceGroupName");

const vnet = new azure.network.VirtualNetwork("vnet", {
    name: vnetName,
    location: location,
    resourceGroupName: resourceGroupName,
    addressSpaces: ["10.0.0.0/16"],
    subnets: [
        { name: "default", addressPrefix: "10.0.1.0/24" },
        { name: "apps",    addressPrefix: "10.0.2.0/24" },
    ],
});

Note: The Classic provider allows defining subnets inline within the VirtualNetwork resource.

App Service Plan and Web App with Classic Provider

ARM Template:

{
  "resources": [
    {
      "type": "Microsoft.Web/serverfarms",
      "apiVersion": "2023-01-01",
      "name": "[parameters('appServicePlanName')]",
      "location": "[parameters('location')]",
      "sku": { "name": "B1", "tier": "Basic", "size": "B1", "capacity": 1 },
      "kind": "linux",
      "properties": { "reserved": true }
    },
    {
      "type": "Microsoft.Web/sites",
      "apiVersion": "2023-01-01",
      "name": "[parameters('webAppName')]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]"
      ],
      "properties": {
        "serverFarmId": "[resourceId('Microsoft.Web/serverfarms', parameters('appServicePlanName'))]",
        "siteConfig": {
          "linuxFxVersion": "NODE|18-lts",
          "appSettings": [{ "name": "WEBSITE_NODE_DEFAULT_VERSION", "value": "~18" }]
        }
      }
    }
  ]
}

Pulumi TypeScript (Classic Provider):

import * as pulumi from "@pulumi/pulumi";
import * as azure from "@pulumi/azure";

const config = new pulumi.Config();
const appServicePlanName = config.require("appServicePlanName");
const webAppName = config.require("webAppName");
const location = config.require("location");
const resourceGroupName = config.require("resourceGroupName");

const appServicePlan = new azure.appservice.ServicePlan("appServicePlan", {
    name: appServicePlanName,
    location: location,
    resourceGroupName: resourceGroupName,
    osType: "Linux",
    skuName: "B1",
});

const webApp = new azure.appservice.LinuxWebApp("webApp", {
    name: webAppName,
    location: location,
    resourceGroupName: resourceGroupName,
    servicePlanId: appServicePlan.id,
    siteConfig: {
        applicationStack: { nodeVersion: "18-lts" },
    },
    appSettings: {
        "WEBSITE_NODE_DEFAULT_VERSION": "~18",
    },
});

Note: The Classic provider has dedicated LinuxWebApp and WindowsWebApp resources with better type safety than the generic WebApp.

Handling Azure-Specific Considerations

TypeScript Output Handling

Azure Native outputs often include undefined. Avoid ! non-null assertions. Always safely unwrap with .apply():

// ❌ WRONG - Will cause TypeScript errors
const webAppUrl = `https://${webApp.defaultHostName!}`;

// ✅ CORRECT - Handle undefined safely
const webAppUrl = webApp.defaultHostName.apply(hostname =>
    hostname ? `https://${hostname}` : ""
);

Resource Naming Conventions

ARM template name property maps to specific naming fields in Pulumi:

// ARM: "name": "myStorageAccount"
// Pulumi:
new azure_native.storage.StorageAccount("logicalName", {
    accountName: "mystorageaccount", // Actual Azure resource name
    // ...
});

API Versions

ARM templates require explicit API versions. Pulumi providers use recent stable API versions by default. Check the Pulumi Registry documentation for which API version each resource uses.

Common Pitfalls to Avoid

• ❌ Not handling Output types properly (missing .apply() in TypeScript)
• ❌ Assuming ARM property names match Pulumi property names exactly
• ❌ Defaulting to the azure classic provider without checking azure-native first — prefer azure-native unless the resource is unsupported or the user explicitly prefers classic abstractions
• ❌ Missing resource dependencies in conversion
• ❌ Not preserving ARM template conditionals and loops
• ❌ Forgetting to convert ARM functions like concat(), uniqueString(), etc.

Importing Azure Resources into Pulumi

This document provides detailed procedures for importing existing Azure resources into Pulumi state and resolving preview diffs to achieve zero-diff validation.

Key Principle: Azure will return many default values it has set dynamically that are not represented in code/state. You must systematically resolve each diff type to achieve zero-diff.

IMPORT APPROACH: INLINE IMPORT IDS

ARM migration uses inline imports. Use Pulumi's import resource option to specify Azure Resource IDs directly in the code.

Example

TypeScript:

const storageAccount = new azure_native.storage.StorageAccount("storageAccount", {
    accountName: "mystorageaccount",
    resourceGroupName: "myResourceGroup",
    location: "eastus",
    sku: { name: "Standard_LRS" },
    kind: "StorageV2",
}, {
    import: "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount"
});

Python:

storage_account = storage.StorageAccount("storageAccount",
    account_name="mystorageaccount",
    resource_group_name="myResourceGroup",
    location="eastus",
    sku=storage.SkuArgs(name="Standard_LRS"),
    kind="StorageV2",
    opts=pulumi.ResourceOptions(
        import_="/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount"
    ))

Go:

storageAccount, err := storage.NewStorageAccount(ctx, "storageAccount", &storage.StorageAccountArgs{
    AccountName:       pulumi.String("mystorageaccount"),
    ResourceGroupName: pulumi.String("myResourceGroup"),
    Location:          pulumi.String("eastus"),
    Sku: &storage.SkuArgs{
        Name: pulumi.String("Standard_LRS"),
    },
    Kind: pulumi.String("StorageV2"),
}, pulumi.Import(pulumi.ID("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount")))

C#:

var storageAccount = new StorageAccount("storageAccount", new StorageAccountArgs
{
    AccountName = "mystorageaccount",
    ResourceGroupName = "myResourceGroup",
    Location = "eastus",
    Sku = new SkuArgs { Name = "Standard_LRS" },
    Kind = "StorageV2",
}, new CustomResourceOptions
{
    ImportId = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount"
});

Java:

var storageAccount = new StorageAccount("storageAccount", StorageAccountArgs.builder()
    .accountName("mystorageaccount")
    .resourceGroupName("myResourceGroup")
    .location("eastus")
    .sku(SkuArgs.builder().name("Standard_LRS").build())
    .kind("StorageV2")
    .build(), CustomResourceOptions.builder()
        .importId("/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount")
        .build());

YAML:

resources:
  storageAccount:
    type: azure-native:storage:StorageAccount
    properties:
      accountName: mystorageaccount
      resourceGroupName: myResourceGroup
      location: eastus
      sku:
        name: Standard_LRS
      kind: StorageV2
    options:
      import: /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount

FINDING IMPORT IDS

Azure Resource IDs follow a predictable pattern and can be generated by convention or queried.

Azure Resource ID Format

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

For child resources, the pattern extends:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{parentResourceType}/{parentResourceName}/{childResourceType}/{childResourceName}

Examples:

# Storage Account
/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Storage/storageAccounts/mystorageaccount

# Web App
/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Web/sites/mywebapp

# Virtual Network Subnet (child resource)
/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myRG/providers/Microsoft.Network/virtualNetworks/myVNet/subnets/mySubnet

Documentation: Azure Resource ID Documentation

Method 1: Convention-Based Generation

// Pattern: /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

const subscriptionId = "00000000-0000-0000-0000-000000000000";
const resourceGroupName = "myResourceGroup";
const storageAccountName = "mystorageaccount";

const importId = `/subscriptions/${subscriptionId}/resourceGroups/${resourceGroupName}/providers/Microsoft.Storage/storageAccounts/${storageAccountName}`;

Method 2: Query Azure API

# Get resource ID directly
az resource show \
  --name mystorageaccount \
  --resource-group myResourceGroup \
  --resource-type "Microsoft.Storage/storageAccounts" \
  --query "id" \
  --output tsv

# List all resources with IDs
az resource list \
  --resource-group myResourceGroup \
  --query "[].{Name:name, Type:type, ID:id}" \
  --output table

# Get ID for specific resource type
az storage account show \
  --name mystorageaccount \
  --resource-group myResourceGroup \
  --query "id" \
  --output tsv

Finding Import IDs in Pulumi Registry

Each resource type in the Pulumi Registry has an "Import" section with the expected ID format:

Example: Storage Account Import

HANDLING CHILD RESOURCES

Some ARM properties are separate resources in Pulumi and must be imported separately:

Example: WebApp Application Settings

ARM Template (Inline):

{
  "type": "Microsoft.Web/sites",
  "properties": {
    "siteConfig": {
      "appSettings": [
        {"name": "WEBSITE_NODE_DEFAULT_VERSION", "value": "14.17.0"}
      ]
    }
  }
}

Pulumi (Separate Resource):

// Main Web App
const webApp = new azure_native.web.WebApp("webApp", {
    name: "mywebapp",
    resourceGroupName: resourceGroup.name,
    // ... other properties
}, {
    import: "/subscriptions/.../Microsoft.Web/sites/mywebapp"
});

// Application Settings (separate resource)
const appSettings = new azure_native.web.WebAppApplicationSettings("appSettings", {
    name: webApp.name,
    resourceGroupName: resourceGroup.name,
    properties: {
        "WEBSITE_NODE_DEFAULT_VERSION": "14.17.0",
    },
}, {
    import: "/subscriptions/.../Microsoft.Web/sites/mywebapp/config/appsettings"
});

Other common examples:

• WebAppAuthSettings - Authentication settings for Web Apps
• WebAppConnectionStrings - Connection strings for Web Apps
• Network Security Group Rules - May be inline or separate depending on ARM template

Documentation: WebAppApplicationSettings

PREVIEW AFTER IMPORT - ZERO DIFF VALIDATION

After importing resources, you MUST run pulumi preview to ensure there are no changes. The goal is zero diff:

• NO updates
• NO replaces
• NO creates
• NO deletes

If there are changes, follow the Preview Resolution Workflow below.

PREVIEW RESOLUTION WORKFLOW

IMPORTANT: Follow these instructions. Avoid over-use of ignoreChanges resource option.

Azure will return many default values it has set dynamically that are not represented in code/state. You must resolve each diff type systematically:

Removed Properties (-) - Missing Defaults

Symptom: Preview shows properties being removed that exist in Azure:

~ azure-native:storage:StorageAccount: (update)
    - minimumTlsVersion: "TLS1_2"
    - allowBlobPublicAccess: false

Resolution: These properties were set by Azure with default values but are missing from your Pulumi code. ADD them to your code:

const storageAccount = new azure_native.storage.StorageAccount("storageAccount", {
    accountName: "mystorageaccount",
    resourceGroupName: resourceGroup.name,
    // ... other properties
    minimumTlsVersion: azure_native.storage.MinimumTlsVersion.TLS1_2, // ADD this
    allowBlobPublicAccess: false, // ADD this
}, {
    import: "...",
});

How to find the correct values:

# Query Azure for actual property values
az resource show \
  --ids "/subscriptions/.../Microsoft.Storage/storageAccounts/mystorageaccount" \
  --query "properties.minimumTlsVersion" \
  --output tsv

# Get full properties
az storage account show \
  --name mystorageaccount \
  --resource-group myResourceGroup \
  --query "properties" \
  --output json

Added Properties (+) - Computed Properties

Symptom: Preview shows properties being added that don't exist in the ARM template:

~ azure-native:storage:StorageAccount: (update)
    + creationTime: "2024-01-15T10:30:00Z"
    + statusOfPrimary: "available"

Resolution: These are computed/read-only properties set by Azure. Use ignoreChanges for these properties ONLY:

const storageAccount = new azure_native.storage.StorageAccount("storageAccount", {
    // ... properties
}, {
    import: "...",
    ignoreChanges: ["creationTime", "statusOfPrimary"],
});

CRITICAL: Only use ignoreChanges for properties that:

1. Are shown as added (+) in the preview diff 2. Do NOT exist in the source ARM template 3. Are computed/read-only properties set by Azure

Documentation: ignoreChanges Resource Option

Changed Properties (~) - Value Mismatches

Symptom: Preview shows properties with different values:

~ azure-native:network:VirtualNetwork: (update)
    ~ enableDdosProtection: true => false

Resolution: Evaluate the change using preview diff and/or Azure API:

Step 1: Query Azure for the actual value:

az network vnet show \
  --name myVNet \
  --resource-group myResourceGroup \
  --query "enableDdosProtection" \
  --output tsv

Step 2: Determine the correct value:

• If Azure shows true, update your code to true
• If the ARM template specified false, investigate why Azure has true (manual change?)
• Match the desired state (what you want), not necessarily what's in Azure

Step 3: Update your code to match the desired state:

const vnet = new azure_native.network.VirtualNetwork("vnet", {
    virtualNetworkName: "myVNet",
    resourceGroupName: resourceGroup.name,
    enableDdosProtection: true, // Match actual Azure state if that's desired
}, {
    import: "...",
});

DEBUGGING WORKFLOW FOR DIFFS

Step-by-step debugging process:

1. Run preview with details:

   pulumi preview --diff --show-config --show-secrets

2. For each diff, identify the property path:

   ~ azure-native:web:WebApp: (update)
       [urn=...]
       ~ siteConfig.alwaysOn: false => true

3. Query Azure for actual value:

   az webapp show \
     --name mywebapp \
     --resource-group myResourceGroup \
     --query "siteConfig.alwaysOn" \
     --output tsv

4. Check Pulumi Registry for property documentation:

• Search for the resource type in Pulumi Registry
• Check property descriptions, types, and defaults

5. Determine resolution strategy:

• Added (+) and not in ARM template -> ignoreChanges
• Removed (-) and exists in Azure -> Add to code
• Changed (~) -> Update code to desired value

6. Apply fix and re-run preview until zero diff is achieved

COMMON AZURE PROPERTIES REQUIRING ATTENTION

Storage Accounts

• creationTime, statusOfPrimary, statusOfSecondary -> ignore (computed)
• minimumTlsVersion, allowBlobPublicAccess -> often need to be added
• encryption.services.* -> may need to be added with defaults

Web Apps

• state, hostNames, repositorySiteName -> ignore (computed)
• httpsOnly, clientAffinityEnabled -> often need to be added
• siteConfig nested properties -> many defaults need explicit values

Virtual Networks

• subnets[*].id, subnets[*].etag -> ignore (computed)
• enableDdosProtection, enableVmProtection -> may need to be added

Network Security Groups

• securityRules[*].etag, securityRules[*].id -> ignore (computed)
• Default rules -> Azure adds default rules; handle via ignoreChanges or import separately

ITERATION PROCESS

The preview resolution process is iterative:

1. Import resources with initial code 2. Run pulumi preview 3. Identify diffs (+ / - / ~) 4. Apply resolution strategy for each diff 5. Run pulumi preview again 6. Repeat until zero diff

Expected iterations: 2-5 preview runs for complex resources

COMMON PITFALLS TO AVOID

• Using ignoreChanges for properties that exist in ARM template
• Not querying Azure API to verify actual property values
• Stopping at first preview without resolving all diffs
• Forgetting to import child resources separately (like WebAppApplicationSettings)
• Not documenting which properties were ignored vs. added