OCI Architecture 101: A Visual Guide to Tenancy, Compartment, and Resource
Congratulations — your account is ready!
If you followed the previous article and signed up for an OCI Always Free account, you should now be logged into the OCI Console. But what comes next will probably be a little confusing.
The First Problem You'll Run Into After Creating Your Account
You open the OCI Console, and your first instinct is probably "let me spin up a VM." But you'll quickly notice a few things:
- When creating a VM, the form asks you to pick a Compartment
- When creating a database, it asks for a Compartment again
- There's a Compartment dropdown filter on the left sidebar — pick the wrong one and all your resources disappear
- Your account seems to only have one thing called root
"What exactly is a Compartment? Why does every action require me to pick one? Should I create a few?"
If you have this question, congratulations — you're asking the right thing.
In the OCI world, understanding the resource hierarchy is more important than spinning up a VM. Because this structure determines three things:
- Who can touch what — access control (IAM Policy)
- Where the money goes — cost tracking (Budget & Cost Analysis)
- Who can see what — resource visibility (Resource Visibility)
This article will walk you through OCI's three-layer architecture — Tenancy → Compartment → Resource — and compare it with GCP's organizational structure. At the end, I'll design a simple but practical Dev / Test / Prod Compartment structure so you can establish good management habits from day one on OCI.
OCI's Three-Layer Architecture: Tenancy → Compartment → Resource
OCI organizes everything into a simple three-layer structure. Think of it like an office building:
| Layer | OCI Concept | Building Analogy |
|---|---|---|
| Layer 1 | Tenancy | The entire building |
| Layer 2 | Compartment | Floors and rooms inside the building |
| Layer 3 | Resource | Office equipment inside the rooms |
Let's break it down layer by layer.
Tenancy: The Starting Point of Your OCI World
The moment you successfully register an OCI account, Oracle creates a Tenancy for you.
One account = one Tenancy — it's that simple.
A Tenancy is your top-level container in OCI. All resources, all configurations, and all billing belong under this Tenancy. Think of it as "your OCI universe" — it has a unique ID (OCID) and a Home Region you selected during registration.
Key point for beginners: You don't need to "create" a Tenancy — it's automatically generated when you sign up. You won't have a second Tenancy unless you register another account.
One thing that's easy to mix up: the Tenancy itself is a Compartment — it's the root Compartment. So when you log into the Console and only see a "root," that IS your Tenancy.
Compartment: The Most Important Concept in OCI
If you remember only one concept from this article, make it this one: Compartment.
A Compartment is a logical container that OCI uses to group and manage resources. It's not a physical data center or network segment — it's an organizational "folder." But this folder is far more powerful than the folders on your computer, because it controls three things:
| Capability | Description | Example |
|---|---|---|
| Access Control | Define "who can do what in this Compartment" via IAM Policy | "The Dev team can only manage resources in the dev-compartment" |
| Cost Tracking | Set Budgets and track spending per Compartment | "How much did the prod environment cost this month?" |
| Resource Visibility | The Console's Compartment filter determines which resources you see | "Switch to test-compartment and only see testing resources" |
Key Properties of Compartments
- Nestable: Compartments can contain other Compartments, up to 6 levels deep. Like floors in a building that can be divided into different rooms
- Resources can be moved: Created a resource in the wrong Compartment? No problem — you can Move it to another Compartment (no need to recreate)
- Policy inheritance: Policies set on a parent Compartment automatically apply to all child Compartments
- Conditional deletion: A Compartment must be empty (no resources inside) before it can be deleted
Advice for beginners: Don't overthink it at the start. Create 2–3 Compartments to separate your environments — you can always adjust later. There's a ready-made template at the end of this article.
Resource: The Things You Actually Use
Resources are the actual service instances you use on OCI. For example:
- A Compute Instance (VM)
- An Autonomous Database
- A VCN (Virtual Cloud Network)
- An OCI Function
- An Object Storage Bucket
Every Resource has a globally unique OCID (Oracle Cloud Identifier) with this format:
ocid1.<resource-type>.<realm>.<region>.<unique-id>
For example: ocid1.instance.oc1.ap-singapore-1.abcdefg12345
Every Resource must live inside a Compartment — just like every desk must be placed in a room. If you pick the wrong Compartment when creating a Resource, don't worry — you can Move it later.
If You've Used GCP: Architecture Comparison
If you have GCP experience, this section will help you quickly build a mental model for OCI. If you're new to cloud, you can also read it in reverse — learn OCI first, then look at GCP, and you'll find the concepts are completely transferable.
GCP's Four-Layer Architecture
GCP's resource hierarchy has one more layer than OCI — four layers in total:
| Layer | GCP Concept | Description |
|---|---|---|
| Layer 1 | Organization | Tied to a Google Workspace or Cloud Identity domain; the top level of the entire organization |
| Layer 2 | Folder | Optional grouping tool, nestable, commonly used to separate teams or environments |
| Layer 3 | Project | GCP's core management unit — all resources live inside a Project |
| Layer 4 | Resource | Compute Engine, Cloud SQL, Cloud Functions, and other actual services |
Visual Comparison: OCI vs GCP
First, the OCI structure:
Now, the GCP structure:
Layer-by-Layer Comparison
| Aspect | OCI | GCP | Key Difference |
|---|---|---|---|
| Top Level | Tenancy | Organization | OCI auto-creates on signup; GCP requires a Google Workspace domain |
| Grouping | Compartment | Folder + Project | OCI handles it in one layer; GCP uses Folder for grouping + Project for management |
| Resource Container | Compartment | Project | Where resources ultimately live. OCI's Compartment plays both "grouping" and "container" roles |
| Nesting | Yes, up to 6 levels | Folder: Yes / Project: No | OCI Compartments can be nested (6-level limit); GCP Projects are flat and cannot be nested |
| Permission Inheritance | Yes, Policy inherits downward | Yes, IAM inherits downward | Same concept, different syntax |
| Billing Unit | Compartment (via Budget) | Project (Billing Account) | GCP bills per Project; OCI tracks via Compartment + Budget |
| Move Resources | Supported | Supported | Both support it, but the process differs |
Key Differences Summary
The biggest difference is that Compartment wears multiple hats:
- In GCP's world, "grouping" and "resource container" are two separate concepts — Folders handle grouping, Projects hold resources. You can have Folders but don't have to.
- In OCI's world, Compartment is both the grouping tool and the resource container. This makes the structure more concise, but also means you need to plan your Compartment hierarchy more carefully.
Remember this: GCP is "Folders for categorization, Projects for resources"; OCI is "Compartments do it all."
Practical Design: Dev / Test / Prod Compartment Structure
Now that you understand the three-layer architecture, the next question is: "How should I plan my Compartments?"
The most common mistake is — throwing everything into the root Compartment.
When you first start using OCI, you might think "it's just me using this, why bother with multiple Compartments?" But as your resources grow, you'll start running into these problems:
- No granular permissions: All Policies are tied to root. Want to restrict an API Key to only access the test environment? Can't do it
- Unclear billing: Prod and dev costs are mixed together — no idea where the money went
- Accidental deletion risk: While cleaning up test resources, you might accidentally delete something from production
The solution is simple: separate your environments from day one.
Recommended Compartment Structure
Here's a basic structure suitable for independent developers or small teams:
Role of Each Compartment
| Compartment | Purpose | What Goes Here |
|---|---|---|
| network | Centralized management of all networking resources | VCN, Subnet, Internet Gateway, Security List, NSG |
| shared-services | Services shared across environments | Vault (key management), Object Storage, Container Registry, Logging |
| dev | Development environment | Dev VMs, databases, test Functions |
| test | Testing / Staging environment | QA validation resources; data can be anonymized copies from prod |
| prod | Production environment | Public-facing VMs, production databases, scheduled Functions |
Why Separate Network and Shared Services?
Network isolation: VCNs are typically shared across environments (dev / test / prod VMs might all be in the same VCN, isolated by different Subnets). Centralizing network resources avoids the chaos of "each environment has its own network setup, and nobody knows which Security List opened which ports."
Shared-services isolation: Some services are inherently cross-environment. For example, the Master Key in Vault won't have separate dev/prod copies; Object Storage backup buckets might be used across environments. Centralizing these shared services makes Policy definitions much cleaner.
Design Principles
Three design principles to wrap up — applicable regardless of your project's scale:
- Environment isolation: Dev / Test / Prod should be independent and not interfere with each other. The ideal state: deleting all resources in the dev Compartment should have zero impact on prod
- Least privilege: Grant only the necessary permissions to each Compartment. For example, a CI/CD Service Account should only access specific resources in the prod Compartment
- Billing transparency: Set a Budget for each Compartment and receive monthly spending reports. Even if you're fully on the free tier now, building this habit will save you countless headaches when you scale up
Summary: One Diagram to Remember OCI Architecture
The entire article condensed into one diagram:
- Tenancy: Your OCI world, auto-created when you sign up
- Compartment: The core unit for grouping + permissions + billing, nestable
- Resource: The actual services you use, must live inside a Compartment
If you've used GCP, remember: OCI's Compartment ≈ GCP's Folder + Project combined.
If you're new to cloud, remember: plan your Compartment structure before you start creating resources. This habit will save you countless headaches down the road.
Want to Learn More?
If you're interested in our technical architecture, check out the System Architecture page to learn about the Data Pipeline and real-time monitoring system behind cb lab.
You're also welcome to join our Telegram channel for daily curated convertible bond strategy updates.
What's Next
This is the second article in the cb lab cloud architecture series. If you haven't read the first one, I recommend starting with What is OCI? Why Independent Developers Should Give Oracle Cloud Infrastructure a Try.
We'll continue diving deeper into each OCI service with hands-on guides:
- Autonomous Database: What Is OLAP? OLTP? OCI ADB Says: Why Not Both?
- OCI Functions: Building an ETL Pipeline with Serverless
- OCI Networking: VCN, Security List, and Firewall Configuration
- OCI Compute: Setting Up and Performance of ARM VMs