oraclecloud-migration-deep-dive

Oracle Cloud Migration Deep Dive

Overview

Migrating to OCI from AWS or Azure requires translating IAM concepts (roles to policies, accounts to compartments), networking (VPC to VCN, Security Groups to NSGs), and compute (AMI to custom image). OCI's migration tooling is underdocumented compared to AWS Migration Hub or Azure Migrate. This skill provides comprehensive concept mapping tables, custom image import procedures, network topology translation, IAM policy translation, and data migration patterns — everything needed for a controlled cloud migration.

Purpose: Translate AWS/Azure architecture into OCI equivalents and execute the migration using OCI CLI and Python SDK, with verification at each step.

Prerequisites

• OCI account with an active tenancy — https://cloud.oracle.com
• OCI CLI installed and configured — ~/.oci/config validated (see oraclecloud-install-auth)
• Python 3.8+ with the OCI SDK — pip install oci
• Source cloud CLI — aws CLI or az CLI for exporting resources
• Object Storage bucket in OCI for staging image imports
• IAM policies: manage objects in compartment, manage custom-images in compartment, manage virtual-network-family in compartment

Instructions

Step 1: AWS-to-OCI Concept Mapping

AWS Concept	OCI Equivalent	Key Differences
Account	Tenancy	One tenancy = one billing entity, use compartments for isolation
Organization OU	Compartment	Compartments are hierarchical, up to 6 levels deep
IAM Role	IAM Policy	OCI policies use allow group X to verb resource in compartment Y syntax
IAM User	IAM User	Same concept, but OCI uses API key auth (not access keys)
VPC	VCN	VCN subnets are regional (not AZ-scoped like AWS)
Security Group	Network Security Group (NSG)	NSGs attach to VNICs, not instances. Also have Security Lists (subnet-level)
Route Table	Route Table	Similar, but OCI route rules target gateway OCIDs
Internet Gateway	Internet Gateway	Identical concept
NAT Gateway	NAT Gateway	Identical concept
VPC Endpoint	Service Gateway	Service Gateway routes to OCI services without internet
VPC Peering	LPG / DRG	LPG for same-region, DRG for cross-region or on-premises
AMI	Custom Image	Export as VMDK/QCOW2, import via Object Storage
EBS	Block Volume	Attachable block storage, similar performance tiers
S3	Object Storage	Compatible API (S3 compatibility mode available)
RDS	Autonomous Database	Fully managed, but different administration model
EC2 Instance Type	Shape	Flex shapes allow fractional OCPU allocation
Availability Zone	Availability Domain (AD)	Same concept, 1-3 ADs per region
CloudWatch	Monitoring Service	Uses MQL (Monitoring Query Language) instead of CloudWatch metrics
CloudTrail	Audit Service	Automatic, no setup required

Step 2: Azure-to-OCI Concept Mapping

Azure Concept	OCI Equivalent	Key Differences
Subscription	Compartment	OCI uses compartments for billing isolation (not separate subscriptions)
Resource Group	Compartment	Compartments are hierarchical; resource groups are flat
Azure AD	OCI IAM / IDCS	OCI Identity Domains replaces IDCS for SSO/federation
VNet	VCN	OCI subnets are regional, not tied to a zone
NSG	NSG	Nearly identical concept
Azure SQL	Autonomous Database	Different scaling model (OCPU-based)
Managed Disk	Block Volume	Similar, but OCI uses volume groups for snapshots
Blob Storage	Object Storage	Different API, but S3-compatible mode available
Azure Monitor	Monitoring Service	MQL query language instead of Kusto
Azure Policy	Cloud Guard	Detective controls, not preventive like Azure Policy

Step 3: Custom Image Import (AWS AMI to OCI)

Export the AMI from AWS, then import to OCI via Object Storage:

# Step 3a: Export AMI from AWS as VMDK
aws ec2 create-store-image-task \
  --image-id ami-0123456789abcdef0 \
  --bucket my-export-bucket

# Step 3b: Download and upload to OCI Object Storage
aws s3 cp s3://my-export-bucket/ami-0123456789abcdef0.vmdk ./image.vmdk

oci os object put \
  --bucket-name migration-staging \
  --file ./image.vmdk \
  --name "imported-image.vmdk" \
  --namespace "$NAMESPACE"

import oci

config = oci.config.from_file("~/.oci/config")
compute = oci.core.ComputeClient(config)

# Step 3c: Import as OCI custom image
image = compute.create_image(
    oci.core.models.CreateImageDetails(
        compartment_id="COMPARTMENT_OCID",
        display_name="migrated-from-aws",
        image_source_details=oci.core.models.ImageSourceViaObjectStorageTupleDetails(
            source_type="objectStorageTuple",
            bucket_name="migration-staging",
            namespace_name="NAMESPACE",
            object_name="imported-image.vmdk",
            source_image_type="VMDK",
        ),
    )
).data

print(f"Image import started: {image.id}")
print(f"State: {image.lifecycle_state}")  # IMPORTING → AVAILABLE

Step 4: IAM Policy Translation

AWS IAM roles use JSON policies attached to entities. OCI uses human-readable policy statements attached to compartments:

# AWS: Allow EC2 instances to read S3
{
  "Effect": "Allow",
  "Action": ["s3:GetObject", "s3:ListBucket"],
  "Resource": "arn:aws:s3:::my-bucket/*"
}

# OCI equivalent:
allow dynamic-group app-instances to read objects in compartment prod where target.bucket.name='my-bucket'

Common IAM translations:

AWS Policy	OCI Policy Statement
AdministratorAccess	allow group admins to manage all-resources in tenancy
ReadOnlyAccess	allow group readers to inspect all-resources in tenancy
AmazonEC2FullAccess	allow group compute-admins to manage instances in compartment prod
AmazonS3ReadOnlyAccess	allow group readers to read objects in compartment prod
AmazonVPCFullAccess	allow group net-admins to manage virtual-network-family in compartment prod

# Create an OCI IAM policy
oci iam policy create \
  --compartment-id "$COMPARTMENT_OCID" \
  --name "app-compute-policy" \
  --description "Allow app team to manage compute in prod" \
  --statements '["allow group app-team to manage instances in compartment prod","allow group app-team to use volumes in compartment prod"]'

Step 5: Network Topology Translation

Translate an AWS VPC with public/private subnets into an OCI VCN:

# Export AWS VPC configuration
aws ec2 describe-vpcs --vpc-ids vpc-0123456789abcdef0 --output json > aws-vpc.json
aws ec2 describe-subnets --filters "Name=vpc-id,Values=vpc-0123456789abcdef0" --output json > aws-subnets.json
aws ec2 describe-route-tables --filters "Name=vpc-id,Values=vpc-0123456789abcdef0" --output json > aws-routes.json

# Create equivalent OCI VCN
oci network vcn create \
  --compartment-id "$COMPARTMENT_OCID" \
  --display-name "migrated-vcn" \
  --cidr-blocks '["10.0.0.0/16"]' \
  --dns-label "migratedvcn"

Step 6: Data Migration (S3 to Object Storage)

OCI Object Storage supports S3-compatible API, enabling direct migration:

import oci

config = oci.config.from_file("~/.oci/config")
os_client = oci.object_storage.ObjectStorageClient(config)
namespace = os_client.get_namespace().data

# Create destination bucket
os_client.create_bucket(
    namespace_name=namespace,
    create_bucket_details=oci.object_storage.models.CreateBucketDetails(
        compartment_id="COMPARTMENT_OCID",
        name="migrated-data",
        storage_tier="Standard",
    ),
)

# Upload objects (for large migrations, use OCI Data Transfer Service)
with open("data-export.csv", "rb") as f:
    os_client.put_object(
        namespace_name=namespace,
        bucket_name="migrated-data",
        object_name="data-export.csv",
        put_object_body=f,
    )

print(f"Uploaded to: https://objectstorage.{config['region']}.oraclecloud.com/n/{namespace}/b/migrated-data/o/data-export.csv")

S3 Compatibility mode for tools that speak S3 natively:

# OCI Object Storage S3-compatible endpoint
# https://<namespace>.compat.objectstorage.<region>.oraclecloud.com

# Use with aws cli (after configuring OCI customer secret keys)
aws s3 sync s3://source-bucket/ s3://migrated-data/ \
  --endpoint-url "https://NAMESPACE.compat.objectstorage.us-ashburn-1.oraclecloud.com"

Output

Successful completion produces:

• AWS-to-OCI and Azure-to-OCI concept mapping tables for architecture translation
• Custom image imported from VMDK into OCI compute (ready to launch instances)
• IAM policies translated from AWS JSON format to OCI policy statements
• Network topology (VCN, subnets, gateways) matching the source VPC/VNet configuration
• Data migrated from S3 to OCI Object Storage via direct upload or S3-compatible API

Error Handling

Error	Code	Cause	Solution
NotAuthorizedOrNotFound	404	Missing IAM policy for image import	Add allow group migrators to manage custom-images in compartment prod
InvalidParameter	400	Unsupported image format	OCI accepts VMDK and QCOW2 only — convert other formats first
NotAuthenticated	401	API key misconfigured	Re-validate: oci iam user get --user-id $(grep ^user ~/.oci/config | cut -d= -f2)
TooManyRequests	429	Rate limited during bulk upload	Add delays between Object Storage uploads — no Retry-After header
InternalError	500	OCI service issue	Retry after 60 seconds; check https://ocistatus.oraclecloud.com
Image import stuck in IMPORTING	—	Large image or Object Storage throttling	Check work request: oci work-requests work-request get --work-request-id <id>

Examples

Quick migration pre-flight check:

# Verify OCI compartment is ready
oci iam compartment get --compartment-id "$COMPARTMENT_OCID" \
  --query 'data.{name:name, state:"lifecycle-state"}' --output table

# Verify Object Storage bucket exists
oci os bucket get --bucket-name migration-staging --namespace "$NAMESPACE" \
  --query 'data.name' --raw-output

# Check image import status
oci compute image list --compartment-id "$COMPARTMENT_OCID" \
  --query 'data[?contains("display-name",`migrated`)].{name:"display-name",state:"lifecycle-state"}' \
  --output table

Resources

• OCI Migration Guide — official migration documentation
• OCI Compute Custom Images — image import/export procedures
• OCI S3 Compatibility API — using S3-compatible tools with OCI
• OCI Python SDK Reference — ComputeClient, ObjectStorageClient APIs
• OCI CLI Reference — command-line interface documentation
• OCI Terraform Provider — infrastructure as code for migrated workloads

Next Steps

After migration, review oraclecloud-reference-architecture to validate the OCI topology, then run oraclecloud-prod-checklist to ensure the migrated environment meets production standards.