Skip to main content
oraclecloud-reference-architecture Standard 3-tier OCI reference architecture with VCN, subnets, gateways, load balancer, compute, and Autonomous DB.
Use when designing a new OCI deployment, translating AWS/Azure patterns, or creating Terraform for OCI infrastructure.
Trigger with "oraclecloud architecture", "oci reference design", "oci 3 tier", "oci vpc design".
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill oraclecloud-reference-architectureThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
More from this repository Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
name oraclecloud-reference-architecture description Standard 3-tier OCI reference architecture with VCN, subnets, gateways, load balancer, compute, and Autonomous DB.
Use when designing a new OCI deployment, translating AWS/Azure patterns, or creating Terraform for OCI infrastructure.
Trigger with "oraclecloud architecture", "oci reference design", "oci 3 tier", "oci vpc design".
allowed-tools Read, Write, Edit, Bash(oci:*), Bash(python3:*), Bash(terraform:*), Grep version 1.7.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","oraclecloud","oci"] compatibility Designed for Claude Code
Oracle Cloud Reference Architecture
Overview
OCI architecture has more moving parts than AWS or Azure. Where AWS has VPC + subnets + internet gateway, OCI has VCN + regional subnets + Internet Gateway + NAT Gateway + Service Gateway + DRG (Dynamic Routing Gateway) + LPG (Local Peering Gateway) โ and getting the routing tables wrong means silent packet drops with no error. This provides the standard 3-tier architecture (web/app/db) with every OCI-specific component wired correctly, plus Terraform code to deploy it.
Purpose: Produce a production-ready 3-tier OCI architecture with correctly configured networking, gateways, security rules, and compute/database tiers โ deployable via Terraform.
Prerequisites
Instructions
Step 1: Architecture Overview
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ OCI Region (us-ashburn-1) โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโ VCN (10.0.0.0/16) โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ โ
โ โ โโโโ Internet GW โโโโ โโโโ NAT GW โโโโ โโโโ Service GW โโโโ โ โ
โ โ โโโโโโโโโโฌโโโโโโโโโโโโ โโโโโโโโฌโโโโโโโโโ โโโโโโโโโฌโโโโโโโโโโโ โ โ
โ โ โ โ โ โ โ
โ โ โโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ Public Subnet (10.0.1.0/24) โ Web Tier โ โ โ
โ โ โ Load Balancer (public) โ routes to App Tier โ โ โ
โ โ โ Bastion Host (optional) โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ Private Subnet (10.0.2.0/24) โ App Tier โ โ โ
โ โ โ Compute Instances (VM.Standard.E4.Flex) โ โ โ
โ โ โ โ NAT GW for outbound internet (patching, APIs) โ โ โ
โ โ โ โ Service GW for OCI services (Object Storage, etc.) โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ Private Subnet (10.0.3.0/24) โ DB Tier โ โ โ
โ โ โ Autonomous Database (ATP or ADW) โ โ โ
โ โ โ โ Service GW only (no internet access) โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ โ
โ โ โโโโ DRG โโโโ โ On-premises or cross-region peering โ โ
โ โ โโโโโโโโโโโโโโ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Step 2: Gateway Types Explained Gateway Purpose Attached To Use Case Internet Gateway Bidirectional internet access Public subnet route table Load balancers, bastion hosts NAT Gateway Outbound-only internet access Private subnet route table App servers needing patches, external APIs Service Gateway Access OCI services without internet Private subnet route table Object Storage, Autonomous DB, OCI APIs DRG (Dynamic Routing Gateway) On-premises / cross-region connectivity VCN attachment VPN, FastConnect, inter-region peering LPG (Local Peering Gateway) VCN-to-VCN within same region VCN attachment Shared services VCN, hub-spoke topology
Step 3: Create the VCN and Subnets (Python SDK) import oci
config = oci.config.from_file("~/.oci/config" )
network = oci.core.VirtualNetworkClient(config)
vcn = network.create_vcn(
oci.core.models.CreateVcnDetails(
compartment_id="COMPARTMENT_OCID" ,
display_name="prod-vcn" ,
cidr_blocks=["10.0.0.0/16" ],
dns_label="prodvcn" ,
)
).data
print (f"VCN created: {vcn.id } " )
web_subnet = network.create_subnet(
oci.core.models.CreateSubnetDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="web-subnet-public" ,
cidr_block="10.0.1.0/24" ,
dns_label="web" ,
prohibit_internet_ingress=False ,
)
).data
app_subnet = network.create_subnet(
oci.core.models.CreateSubnetDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="app-subnet-private" ,
cidr_block="10.0.2.0/24" ,
dns_label="app" ,
prohibit_internet_ingress=True ,
)
).data
db_subnet = network.create_subnet(
oci.core.models.CreateSubnetDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="db-subnet-private" ,
cidr_block="10.0.3.0/24" ,
dns_label="db" ,
prohibit_internet_ingress=True ,
)
).data
print (f"Subnets: web={web_subnet.id } , app={app_subnet.id } , db={db_subnet.id } " )
Step 4: Create Gateways and Route Tables
igw = network.create_internet_gateway(
oci.core.models.CreateInternetGatewayDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="prod-igw" ,
is_enabled=True ,
)
).data
nat = network.create_nat_gateway(
oci.core.models.CreateNatGatewayDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="prod-nat" ,
)
).data
services = network.list_services().data
all_services = next (s for s in services if "All" in s.name)
sgw = network.create_service_gateway(
oci.core.models.CreateServiceGatewayDetails(
compartment_id="COMPARTMENT_OCID" ,
vcn_id=vcn.id ,
display_name="prod-sgw" ,
services=[oci.core.models.ServiceIdRequestDetails(service_id=all_services.id )],
)
).data
print (f"Gateways: igw={igw.id } , nat={nat.id } , sgw={sgw.id } " )
Step 5: Terraform Deployment # provider.tf
terraform {
required_providers {
oci = {
source = "oracle/oci"
version = ">= 5.0"
}
}
}
provider "oci" {
config_file_profile = "DEFAULT"
}
# vcn.tf
resource "oci_core_vcn" "prod" {
compartment_id = var.compartment_id
display_name = "prod-vcn"
cidr_blocks = ["10.0.0.0/16"]
dns_label = "prodvcn"
}
resource "oci_core_internet_gateway" "prod" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "prod-igw"
enabled = true
}
resource "oci_core_nat_gateway" "prod" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "prod-nat"
}
resource "oci_core_subnet" "web" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "web-subnet-public"
cidr_block = "10.0.1.0/24"
dns_label = "web"
prohibit_internet_ingress = false
route_table_id = oci_core_route_table.public.id
security_list_ids = [oci_core_security_list.web.id]
}
resource "oci_core_subnet" "app" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "app-subnet-private"
cidr_block = "10.0.2.0/24"
dns_label = "app"
prohibit_internet_ingress = true
route_table_id = oci_core_route_table.private.id
security_list_ids = [oci_core_security_list.app.id]
}
resource "oci_core_route_table" "public" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "public-rt"
route_rules {
destination = "0.0.0.0/0"
network_entity_id = oci_core_internet_gateway.prod.id
}
}
resource "oci_core_route_table" "private" {
compartment_id = var.compartment_id
vcn_id = oci_core_vcn.prod.id
display_name = "private-rt"
route_rules {
destination = "0.0.0.0/0"
network_entity_id = oci_core_nat_gateway.prod.id
}
}
Step 6: Component Mapping (AWS/Azure โ OCI) Concept AWS Azure OCI Virtual network VPC VNet VCN Subnet Subnet (AZ-scoped) Subnet Subnet (regional) Internet access Internet Gateway โ (default) Internet Gateway Outbound only NAT Gateway NAT Gateway NAT Gateway Private service access VPC Endpoint Private Endpoint Service Gateway Cross-network peering VPC Peering VNet Peering LPG / DRG Firewall rules Security Group NSG NSG + Security List Load balancer ALB/NLB Azure LB OCI Load Balancer Managed database RDS/Aurora Azure SQL Autonomous Database
Output Successful completion produces:
A 3-tier VCN architecture with public (web), private (app), and private (db) subnets
Internet Gateway, NAT Gateway, and Service Gateway correctly routed to their respective subnets
Route tables with proper rules (public โ IGW, private โ NAT/SGW)
Terraform code deployable with terraform plan && terraform apply
Component mapping table for teams coming from AWS or Azure
Error Handling Error Code Cause Solution NotAuthorizedOrNotFound 404 Missing IAM policy for VCN creation Add allow group netadmins to manage virtual-network-family in compartment prod InvalidParameter 400 Overlapping CIDR blocks Ensure VCN CIDR does not overlap with existing VCNs or on-premises networks LimitExceeded 400 Hit VCN or subnet service limit Request limit increase via Console > Governance > Service Limits TooManyRequests 429 Rate limited during bulk creation Add 2-second delays between resource creation calls InternalError 500 OCI service issue during provisioning Retry after 60 seconds; check https://ocistatus.oraclecloud.com Terraform provider crash โ OCI provider version incompatibility Pin provider: version = "~> 5.0" (see oraclecloud-upgrade-migration)
Examples Quick VCN validation (CLI):
oci network vcn list \
--compartment-id "$COMPARTMENT_OCID " \
--query 'data[].{name:"display-name", cidr:"cidr-blocks", state:"lifecycle-state"}' \
--output table
oci network subnet list \
--compartment-id "$COMPARTMENT_OCID " \
--vcn-id "$VCN_OCID " \
--query 'data[].{name:"display-name", cidr:"cidr-block", public:"prohibit-internet-ingress"}' \
--output table
Validate route table connectivity:
oci network route-table get --rt-id "$PUBLIC_RT_OCID " \
--query 'data."route-rules"[].{dest:destination, target:"network-entity-id"}' \
--output table
Resources
Next Steps After deploying the architecture, run oraclecloud-prod-checklist to validate production readiness, or see oraclecloud-migration-deep-dive for translating existing AWS/Azure workloads into this architecture pattern.
