oraclecloud-upgrade-migration

Oracle Cloud Upgrade & Migration

Overview

OCI Terraform provider and Python SDK break backwards compatibility more often than AWS equivalents. The Terraform provider has had provider crashes on terraform plan after upgrades, deprecated resource types removed without migration paths, and schema changes that silently alter behavior. The Python SDK has had memory leak fixes that changed object lifecycle semantics and authentication class renames between minor versions. This skill tracks known breaking changes and provides safe upgrade patterns with version pinning, pre-upgrade testing, and rollback procedures.

Purpose: Upgrade OCI Python SDK and Terraform provider versions safely, detect breaking changes before they hit production, and roll back cleanly if an upgrade fails.

Prerequisites

• Python 3.8+ with the current OCI SDK installed — pip show oci
• Terraform 1.5+ with the OCI provider — terraform version
• OCI CLI installed — oci --version
• Git for version control of infrastructure code
• A test environment — never upgrade directly in production
• Current ~/.oci/config validated (see oraclecloud-install-auth)

Instructions

Step 1: Audit Current Versions

# Python SDK version
pip show oci | grep -E "^(Name|Version|Location)"
# Example: Version: 2.125.0

# OCI CLI version
oci --version
# Example: 3.41.0

# Terraform provider version
grep -A2 'oracle/oci' .terraform.lock.hcl 2>/dev/null || echo "No lock file found"
terraform providers
# Example: oracle/oci v5.46.0

import oci
print(f"OCI SDK version: {oci.__version__}")

Step 2: Check for Known Breaking Changes

Python SDK known breaking changes:

Version	Breaking Change	Impact	Mitigation
2.120.0+	oci.retry module refactored	Custom retry strategies may break	Update to oci.retry.retry.RetryStrategyBuilder
2.115.0+	oci.config.validate_config() stricter	Rejects configs with extra fields	Remove non-standard fields from ~/.oci/config
2.105.0+	Composite operations return type changed	.data attribute structure changed	Check .data type assertions in your code
2.90.0+	wait_for_state deprecated on some clients	Direct get_* polling required	Use oci.wait_until() helper instead

Terraform provider known breaking changes:

Version	Breaking Change	Impact	Mitigation
5.40.0+	oci_core_instance schema change	source_details block restructured	Run terraform plan before apply to detect drift
5.30.0+	Deprecated oci_core_virtual_network removed	Must use oci_core_vcn	Search-and-replace in all .tf files
5.20.0+	Provider crashes on terraform plan with certain instance configs	Segfault in provider binary	Pin to 5.19.x until hotfix release
5.0.0	Major version bump — multiple resources renamed	State file references break	Use terraform state mv for renamed resources

Step 3: Python SDK Safe Upgrade

# Step 3a: Pin current version as fallback
pip freeze | grep ^oci > requirements-oci-backup.txt
echo "Current version saved to requirements-oci-backup.txt"

# Step 3b: Create an isolated branch
git checkout -b upgrade/oci-sdk-$(date +%Y%m%d)

# Step 3c: Upgrade with version constraint
pip install --upgrade "oci>=2.125.0,<2.130.0"  # Constrain to minor range
pip show oci | grep Version

# Step 3d: Run validation script
import oci

config = oci.config.from_file("~/.oci/config")
oci.config.validate_config(config)

# Test core client instantiation
identity = oci.identity.IdentityClient(config)
compute = oci.core.ComputeClient(config)
network = oci.core.VirtualNetworkClient(config)
storage = oci.object_storage.ObjectStorageClient(config)
database = oci.database.DatabaseClient(config)
monitoring = oci.monitoring.MonitoringClient(config)

# Verify each client can make a basic call
identity.list_regions()
print("IdentityClient: OK")

compute.list_instances(compartment_id=config["tenancy"], limit=1)
print("ComputeClient: OK")

network.list_vcns(compartment_id=config["tenancy"], limit=1)
print("VirtualNetworkClient: OK")

namespace = storage.get_namespace().data
print(f"ObjectStorageClient: OK (namespace={namespace})")

print(f"\nAll clients validated on oci=={oci.__version__}")

Step 4: Terraform Provider Safe Upgrade

# Step 4a: Record current state
terraform version > terraform-version-backup.txt
cp .terraform.lock.hcl .terraform.lock.hcl.backup

# Step 4b: Pin provider version in required_providers

# versions.tf — pin to specific minor version
terraform {
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = "~> 5.46.0"  # Allows 5.46.x patches only
    }
  }
}

# Step 4c: Upgrade provider
terraform init -upgrade

# Step 4d: Run plan to detect breaking changes (NEVER skip this)
terraform plan -out=upgrade-plan.tfplan 2>&1 | tee upgrade-plan.log

# Step 4e: Check for unexpected changes
grep -E "(must be replaced|forces replacement|will be destroyed)" upgrade-plan.log
# If any resources are being replaced unexpectedly, STOP and investigate

Step 5: Deprecation Detection Script

Scan your codebase for deprecated OCI resource types and SDK patterns:

#!/bin/bash
echo "=== Deprecated Terraform Resources ==="
grep -rn "oci_core_virtual_network" *.tf 2>/dev/null && echo "  DEPRECATED: Use oci_core_vcn" || echo "  None found"
grep -rn "oci_core_security_list" *.tf 2>/dev/null && echo "  WARNING: Prefer oci_core_network_security_group" || echo "  None found"

echo ""
echo "=== Deprecated Python SDK Patterns ==="
grep -rn "from oci.core import" *.py 2>/dev/null | grep -v "ComputeClient\|VirtualNetworkClient\|BlockstorageClient" && echo "  Check for deprecated imports" || echo "  None found"
grep -rn "wait_for_state" *.py 2>/dev/null && echo "  DEPRECATED: Use oci.wait_until() instead" || echo "  None found"

Step 6: OCI CLI Upgrade

# Check current version
oci --version

# Upgrade via pip (OCI CLI is a Python package)
pip install --upgrade oci-cli

# Verify CLI still works after upgrade
oci iam region list --output table && echo "CLI upgrade: OK" || echo "CLI upgrade: FAILED"

# If CLI breaks, rollback
pip install oci-cli==3.41.0  # Replace with your backup version

Step 7: Rollback Procedures

Python SDK rollback:

# Restore pinned version
pip install -r requirements-oci-backup.txt
pip show oci | grep Version

Terraform provider rollback:

# Restore lock file
cp .terraform.lock.hcl.backup .terraform.lock.hcl
terraform init

# Verify state is intact
terraform plan  # Should show no changes

Git-level rollback:

# Discard upgrade branch entirely
git checkout main
git branch -D upgrade/oci-sdk-$(date +%Y%m%d)

Output

Successful completion produces:

• Version audit showing current OCI SDK, CLI, and Terraform provider versions
• Breaking change assessment against the known issues table
• Upgraded Python SDK with all core clients validated (Identity, Compute, Network, Storage, Database, Monitoring)
• Upgraded Terraform provider with a clean terraform plan showing no unexpected resource replacements
• Deprecation scan results for both Terraform resources and Python SDK patterns
• Backup files for rollback (requirements-oci-backup.txt, .terraform.lock.hcl.backup)

Error Handling

Error	Code	Cause	Solution
ModuleNotFoundError: oci	—	SDK uninstalled during upgrade	pip install oci — start upgrade process over
Terraform provider crash (segfault)	—	Known provider bug in certain versions	Pin to last known good version (check Terraform registry issues)
terraform plan shows unexpected replacements	—	Schema change in provider	Review the plan carefully; use terraform state mv if resources were renamed
NotAuthenticated	401	SDK upgrade changed auth behavior	Re-validate config: python3 -c "import oci; oci.config.validate_config(oci.config.from_file())"
CERTIFICATE_VERIFY_FAILED	—	New SDK version uses updated cert bundle	Install certifi: pip install --upgrade certifi
terraform init fails on lock file	—	Lock file hash mismatch after provider upgrade	Delete .terraform.lock.hcl and re-run terraform init

Examples

Quick version check one-liner:

echo "SDK: $(python3 -c 'import oci; print(oci.__version__)' 2>/dev/null || echo 'not installed')" && \
echo "CLI: $(oci --version 2>/dev/null || echo 'not installed')" && \
echo "TF: $(terraform version -json 2>/dev/null | python3 -c 'import sys,json; d=json.load(sys.stdin); [print(f"  {k}: {v}") for k,v in d.get("provider_selections",{}).items()]' || echo 'not installed')"

Automated upgrade test script:

#!/bin/bash
set -euo pipefail
echo "=== OCI Upgrade Test ==="
pip install --upgrade oci oci-cli
python3 -c "
import oci
config = oci.config.from_file()
oci.config.validate_config(config)
oci.identity.IdentityClient(config).list_regions()
print(f'SDK {oci.__version__}: PASS')
"
oci iam region list --output table > /dev/null && echo "CLI: PASS" || echo "CLI: FAIL"
echo "=== Done ==="

Resources

• OCI Python SDK Changelog — version-by-version changes
• OCI Terraform Provider Releases — provider documentation and changelogs
• OCI CLI Release Notes — CLI version history
• OCI Python SDK Reference — full API documentation
• SDK Troubleshooting — common upgrade and connectivity issues
• OCI Known Issues — platform-known issues affecting SDK/provider

Next Steps

After upgrading, run oraclecloud-prod-checklist to verify the environment still passes all production checks, or see oraclecloud-common-errors for debugging any new error patterns introduced by the upgrade.