dirien/yet-another-agent-harness / .claude/skills/pulumi-arm-to-pulumi
pulumi-arm-to-pulumi
VerifiedConvert 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.3 KB |
| agents/openai.yaml | config | 238 B |
| arm-import.md | markdown | 13.4 KB |
arm-import.md
View on GitHub# 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:**
```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:**
```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:**
```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#:**
```csharp
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:**
```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:**
```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
```text
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
```
For child resources, the pattern extends:
```text
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{parentResourceType}/{parentResourceName}/{childResourceType}/{childResourceName}
```
**Examples:**
```text
# 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](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource)
### Method 1: Convention-Based Generation
```typescript
// 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
```bash
# 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](https://www.pulumi.com/registry/packages/azure-native/api-docs/storage/storageaccount/#import)
## HANDLING CHILD RESOURCES
Some ARM properties are separate resources in Pulumi and must be imported separately:
### Example: WebApp Application Settings
**ARM Template (Inline):**
```json
{
"type": "Microsoft.Web/sites",
"properties": {
"siteConfig": {
"appSettings": [
{"name": "WEBSITE_NODE_DEFAULT_VERSION", "value": "14.17.0"}
]
}
}
}
```
**Pulumi (Separate Resource):**
```typescript
// 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](https://www.pulumi.com/registry/packages/azure-native/api-docs/web/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:
```text
~ 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:**
```typescript
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:**
```bash
# 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:
```text
~ 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:
```typescript
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](https://www.pulumi.com/docs/iac/concepts/options/ignorechanges/)
### Changed Properties (~) - Value Mismatches
**Symptom:** Preview shows properties with different values:
```text
~ 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:
```bash
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:
```typescript
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:**
```bash
pulumi preview --diff --show-config --show-secrets
```
2. **For each diff, identify the property path:**
```text
~ azure-native:web:WebApp: (update)
[urn=...]
~ siteConfig.alwaysOn: false => true
```
3. **Query Azure for actual value:**
```bash
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](https://www.pulumi.com/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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |