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

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:

oci.retry

oci.retry.retry.RetryStrategyBuilder

oci.config.validate_config()

~/.oci/config

.data

.data

wait_for_state

get_*

oci.wait_until()

Terraform provider known breaking changes:

oci_core_instance

source_details

terraform plan

oci_core_virtual_network

oci_core_vcn

.tf

terraform plan

terraform state mv

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

ModuleNotFoundError: oci

pip install oci

terraform plan

terraform state mv

python3 -c "import oci; oci.config.validate_config(oci.config.from_file())"

certifi

pip install --upgrade certifi

terraform init

.terraform.lock.hcl

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

oraclecloud-common-errors