Provider Upgrade Analysis

Overview

Analyze the impact of upgrading Terraform providers or modules before making changes. Identify breaking changes, deprecations, and required code modifications.

Announce at start: “I’m using the provider-upgrade-analysis skill to assess this upgrade.”

Process

Step 1: Identify Current State

# Current Terraform version
terraform version

# Current provider versions
terraform providers

# Lock file details
cat .terraform.lock.hcl

Step 2: Identify Target Version

Determine what version to upgrade to:

• Latest stable
• Specific version requested
• Next major/minor version

Step 3: Research Breaking Changes

For each provider/module upgrade:

AWS Provider Example

# Check CHANGELOG
# https://github.com/hashicorp/terraform-provider-aws/blob/main/CHANGELOG.md

# Check UPGRADE guide for major versions
# https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/version-5-upgrade

Key Sources

Step 4: Analyze Impact

Breaking Changes Categories

Code Scan

Search for affected resources/attributes:

# Find usage of deprecated resource
grep -r "aws_deprecated_resource" --include="*.tf"

# Find usage of removed argument
grep -r "removed_argument" --include="*.tf"

Step 5: Check Memory

Query memory/global/provider-issues.json for:

• Known issues with target version
• Past upgrade experiences
• Workarounds needed

Step 6: Generate Report

## Provider Upgrade Analysis

### Summary

| Provider | Current | Target | Risk Level |
|----------|---------|--------|------------|
| aws | 4.67.0 | 5.0.0 | HIGH |

### Breaking Changes

#### 1. [Change Name]
- **Type:** Removed Argument
- **Affected Resource:** `aws_instance`
- **Attribute:** `ebs_optimized` default changed
- **Impact:** Instances may change on next apply
- **Required Action:** Explicitly set `ebs_optimized = true`
- **Files Affected:**
  - `modules/compute/main.tf:45`
  - `environments/prod/instances.tf:23`

#### 2. [Change Name]
...

### Deprecations (Future Concern)

| Resource/Attribute | Deprecated In | Removed In | Replacement |
|-------------------|---------------|------------|-------------|
| `aws_old_thing` | 4.50.0 | 5.0.0 | `aws_new_thing` |

### State Migration Required

- [ ] Resource `aws_old` → `aws_new` requires state mv
- [ ] [Other migrations]

### Recommended Upgrade Path

1. **Backup state**
   ```bash
   terraform state pull > backup-$(date +%Y%m%d).tfstate

2. Update version constraint

   terraform {
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 5.0"
       }
     }
   }
   

3. Run init

   terraform init -upgrade
   

4. Apply code changes [List of required changes]

5. Run plan

   terraform plan
   

6. Review and apply [After careful review]

Risk Assessment

Known Issues

[From memory or research]

### Step 7: Update Memory

Store findings in `memory/global/provider-issues.json`:
```json
{
  "aws": {
    "5.0.0": {
      "known_issues": [...],
      "upgrade_notes": [...],
      "last_updated": "2024-01-15"
    }
  }
}

Common Upgrade Patterns

Major Version Upgrades (e.g., 4.x → 5.x)

• Usually have breaking changes
• Check upgrade guide thoroughly
• Plan for state migrations
• Test in non-prod first

Minor Version Upgrades (e.g., 5.1 → 5.2)

• Usually backward compatible
• Check for deprecation warnings
• Review CHANGELOG for new features

Patch Version Upgrades (e.g., 5.1.0 → 5.1.1)

• Bug fixes only
• Generally safe to apply
• Still review CHANGELOG

Safety Checklist

Before recommending upgrade:

• Breaking changes documented
• Code changes identified
• State migrations planned
• Rollback procedure defined
• Test environment validated
• User informed of risks