
best-practices
Use when architecting OCI solutions, migrating from AWS/Azure, designing multi-AD deployments, or avoiding common OCI anti-patterns. Covers VCN sizing mistakes, Cloud Guard gotchas, free tier specifics, OCI terminology confusion, and multi-AD patterns.
- Installs
- 113
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/acedergren/oci-agent-skills --skill best-practices- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads best-practices automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
OCI Best Practices - Expert Knowledge
🏗️ Use OCI Landing Zone Terraform Modules
Don't reinvent the wheel. Use oracle-terraform-modules/landing-zone for OCI architecture.
Landing Zone solves:
- ❌ Bad Practice #1: Generic compartments (Landing Zone provides hierarchical Network/Security/Workloads structure)
- ❌ Bad Practice #2: Administrator for daily ops (Landing Zone enforces least-privilege IAM policies)
- ❌ Bad Practice #4: Poor network segmentation (Landing Zone implements hub-spoke topology with security zones)
- ❌ Bad Practice #8: Creating your own Terraform modules (Landing Zone provides battle-tested, Oracle-maintained, CIS-certified modules)
This skill provides: OCI-specific anti-patterns, architecture patterns, and operational knowledge for resources deployed WITHIN a Landing Zone.
⚠️ OCI CLI/API Knowledge Gap
You don't know OCI CLI commands or OCI API structure.
Your training data has limited and outdated knowledge of:
- OCI CLI syntax and parameters (updates monthly)
- OCI API endpoints and request/response formats
- OCI service-specific commands and flags
- Latest OCI features, limits, and regional availability
- CIS Benchmark requirements for OCI
When OCI operations are needed:
- Use exact CLI commands from skill references
- Do NOT guess OCI CLI syntax or parameters
- Do NOT assume API endpoint structures
- Reference landing-zones skill for Terraform modules
What you DO know:
- General cloud architecture concepts
- Security principles and compliance frameworks
- Multi-tier application design patterns
This skill bridges the gap by providing current OCI-specific patterns and anti-patterns.
You are an OCI architecture expert. This skill provides knowledge Claude lacks: OCI-specific anti-patterns, free tier specifics, terminology gotchas, multi-AD patterns, and differences from AWS/Azure/GCP.
NEVER Do This
❌ NEVER use /24 or smaller VCN CIDR (cannot expand)
# WRONG - VCN too small, cannot expand later (OCI limitation)
oci network vcn create --cidr-block "10.0.0.0/24"
# Only 256 IPs total, exhausted quickly
# WRONG - copying AWS habit (/16 VPC default)
# OCI supports larger: /16 to /30
# RIGHT - start with /16, plan for growth
oci network vcn create --cidr-block "10.0.0.0/16"
# 65,536 IPs, room for 256 /24 subnets
# CRITICAL: OCI VCNs CANNOT be resized after creation
# Must create new VCN and migrate if too small
Migration cost: Recreating VCN = hours of downtime, IP changes, security rule updates
❌ NEVER use AD-specific subnets (breaks multi-AD HA)
# WRONG - subnet tied to single AD
oci network subnet create \
--vcn-id <vcn-ocid> \
--cidr-block "10.0.1.0/24" \
--availability-domain "fMgC:US-ASHBURN-AD-1" # AD-specific!
# Problem: Can't launch instances in other ADs, no HA
# RIGHT - regional subnet (works in all ADs)
oci network subnet create \
--vcn-id <vcn-ocid> \
--cidr-block "10.0.1.0/24"
# No --availability-domain flag = regional
# Instances can be in any AD in region
Gotcha: Some old OCI guides show AD-specific subnets (deprecated pattern)
❌ NEVER confuse Security Lists vs NSGs (different use cases)
OCI has TWO network security mechanisms:
Security Lists (stateful, subnet-level):
- Applied to ALL resources in subnet
- Use for: Broad rules (internet egress, DNS)
- Limit: 5 per subnet
- Changes: Affect all instances in subnet
Network Security Groups (NSG, resource-level):
- Applied to specific resources
- Use for: Granular rules (app tier → DB tier)
- Limit: 5 per resource, 120 rules per NSG
- Changes: Affect only tagged resources
# WRONG - using Security Lists for app-specific rules
Security List: Allow app-tier → database (applies to ENTIRE subnet)
# RIGHT - use NSG for app-tier resources
NSG "app-tier": Allow egress to NSG "db-tier" on port 1521
# Only instances in app-tier NSG can reach DB
Best practice: Security Lists for baseline (internet, DNS), NSGs for application-specific rules
❌ NEVER assume single-AD deployment is acceptable (no SLA)
OCI Availability Domains (ADs):
- 3 ADs per region (most regions)
- Isolated fault domains
- <1ms latency between ADs
# WRONG - all resources in single AD
All instances in AD-1 → AD failure = complete outage
# RIGHT - distribute across ADs
Production instances: AD-1, AD-2, AD-3
Load balancer: Automatically multi-AD
Database: Autonomous (auto 3-AD) or RAC (2+ nodes)
SLA impact:
Single-AD: NO SLA (OCI doesn't guarantee)
Multi-AD: 99.95% SLA
Critical: Oracle refuses SLA claims for single-AD deployments in regions with 3 ADs
❌ NEVER hardcode AD names (tenant-specific)
# WRONG - AD names are tenant-specific, not portable
availability_domain = "fMgC:US-ASHBURN-AD-1" # Only works in YOUR tenancy!
# Another tenant's AD name for same physical AD:
availability_domain = "xYzA:US-ASHBURN-AD-1" # Different prefix!
# RIGHT - query AD names dynamically
data "oci_identity_availability_domains" "ads" {
compartment_id = var.tenancy_ocid
}
resource "oci_core_instance" "web" {
availability_domain = data.oci_identity_availability_domains.ads.availability_domains[0].name
}
Why: OCI generates unique AD prefixes per tenant for security isolation
❌ NEVER enable Cloud Guard auto-remediation without testing
Cloud Guard = OCI threat detection + auto-response
# DANGER - auto-remediation can break production
Detector: "Public bucket detected"
Auto-remediation: Make bucket private → breaks public website!
Detector: "Security list allows 0.0.0.0/0"
Auto-remediation: Remove rule → breaks internet access!
# SAFER approach:
1. Enable detectors (read-only mode first)
2. Review findings for 1-2 weeks
3. Tune responders to avoid false positives
4. Enable auto-remediation for trusted patterns only
Gotcha: Cloud Guard enabled by default in some tenancies, can auto-break things
❌ NEVER assume you need Oracle Linux (common misconception)
OCI supports:
✓ Oracle Linux (free, optimized)
✓ Ubuntu, CentOS, Rocky Linux (free)
✓ Windows Server (BYOL or license-included)
✓ Custom images (import your own)
# WRONG assumption: "OCI = must use Oracle Linux"
Reality: Any Linux works, Ubuntu has larger community
# Cost: Oracle Linux is FREE (no license cost)
# But if team knows Ubuntu → use Ubuntu
Marketing confusion: Oracle pushes Oracle Linux, but it's not required
OCI Always-Free Tier (Exact Limits)
Generous permanent free tier (no credit card trial, no expiration):
Compute
- 2 AMD VMs: VM.Standard.E2.1.Micro (1/8 OCPU, 1 GB RAM each)
- 4 Arm OCPUs: VM.Standard.A1.Flex (allocate as 1×4 OCPU or 4×1 OCPU)
- Up to 24 GB total RAM (6 GB per OCPU)
- Example: Run 4× 1OCPU/6GB Arm instances free forever
Database
- 2 Autonomous Databases: 1 OCPU each, 20 GB storage per ADB
- Can be ATP or ADW
- Limit: 2 total per tenancy across all regions
Storage
- Block volumes: 200 GB total (2× 100 GB boot volumes + custom)
- Object storage: 10 GB Standard tier
- Archive storage: 10 GB Archive tier
- Block volume backups: 10 GB
Networking
- Load balancer: 1 flexible LB, 10 Mbps bandwidth
- VCN: 2 VCNs per region (free, no OCID cost)
- Public IPv4: 1 reserved public IP free per region
Observability
- Monitoring: 1 billion data points ingested
- Logging: 10 GB ingested per month
- Notifications: 1 million emails per month
Always-Free Gotchas
CRITICAL limits often missed:
# Gotcha 1: 2 ADB limit is TENANCY-wide, not per region
Can have: 1 ATP in Phoenix + 1 ADW in Ashburn = 2 (limit reached)
Cannot: Add 3rd ADB in any region
# Gotcha 2: Arm instances must be VM.Standard.A1.Flex only
Cannot: Use newer A2 shapes (paid only)
# Gotcha 3: Free tier != trial credits
Free tier: Permanent, no expiration
Trial: $300 credit for 30 days (separate)
# Gotcha 4: Stopped ADB counts toward 2 ADB limit
To free slot: Must DELETE ADB, not just STOP
OCI Terminology vs AWS/Azure
Migrating from AWS/Azure? Terminology traps:
| OCI Term | AWS Equivalent | Azure Equivalent |
|---|---|---|
| VCN | VPC | Virtual Network |
| Subnet | Subnet | Subnet |
| Security List | VPC Security Group | NSG (network-level) |
| NSG | Security Group | Application Security Group |
| DRG | Virtual Private Gateway | VPN Gateway |
| Compartment | Resource Group / OU | Resource Group |
| Tenancy | Account | Subscription |
| Region | Region | Region |
| AD (Availability Domain) | Availability Zone | Availability Zone |
| Fault Domain | (within AZ) | Availability Set |
| Dynamic Group | IAM Role (for instances) | Managed Identity |
| Instance Principal | EC2 Instance Profile | Managed Identity |
| OCIR | ECR | Container Registry |
| OKE | EKS | AKS |
Critical difference: OCI has both Security Lists (subnet) and NSGs (resource). AWS only has Security Groups (resource-level).
Multi-AD Architecture Patterns
OCI multi-AD specifics:
AD Distribution Strategy
OCI Regions with 3 ADs (most regions):
- US: Phoenix, Ashburn
- UK: London
- DE: Frankfurt
- AU: Sydney, Melbourne
Pattern: Distribute instances across all 3 ADs
AD-1: Web tier (2 instances) + DB primary
AD-2: Web tier (2 instances) + DB standby
AD-3: Web tier (2 instances) + DB standby
Load Balancer: Automatically spans ADs
Gotcha: Some shapes only available in specific ADs (check first)
# Check shape availability by AD
oci compute shape list \
--compartment-id <ocid> \
--availability-domain "fMgC:US-ASHBURN-AD-1"
Fault Domain Additional Layer
Within each AD, OCI has Fault Domains (FD):
- 3 FDs per AD
- Separate power, cooling, network
- <1ms latency within AD
Best practice: Spread instances across ADs AND FDs
AD-1:
FD-1: Web instance 1
FD-2: Web instance 2
FD-3: Web instance 3
AD-2:
FD-1: Web instance 4
(repeat pattern)
Protection:
- AD failure: 2 ADs survive (66% capacity)
- FD failure: Only 1 instance affected (16% capacity)
When to use FDs: Only for extra-critical apps (adds complexity)
Compartment Strategy Best Practices
Compartment hierarchy (OCI-specific IAM boundary):
Root Compartment (tenancy)
│
├─ SharedServices (networking, security)
│ ├─ Network (VCNs, DRGs)
│ └─ Security (Vault, KMS, Cloud Guard)
│
├─ Production
│ ├─ App1
│ │ ├─ Compute
│ │ ├─ Database
│ │ └─ Storage
│ └─ App2
│
├─ NonProduction
│ ├─ Development
│ ├─ Testing
│ └─ Staging
│
└─ Sandbox (developers, auto-cleanup)
Key principles:
- Billing separation: Compartment tags enable cost reporting by environment
- IAM boundaries: Policies scoped to compartments (least privilege)
- Quota isolation: Separate limits per compartment
- Lifecycle: Delete entire compartment = deletes all resources inside
Anti-pattern: Flat structure with no hierarchy (AWS account-per-env habit)
Cost Optimization OCI-Specific
Flex Shape Savings (Unique to OCI)
Fixed shapes (legacy):
VM.Standard2.4: 4 OCPUs, 60 GB RAM, $218/month
Flex shapes (right-size RAM independently):
VM.Standard.E4.Flex: 4 OCPUs, 16 GB RAM, $109/month (50% savings)
Flex advantage: Pay only for RAM you need
- 1 OCPU = 1-64 GB RAM configurable
- Most apps don't need 15GB per OCPU (fixed ratio)
Migration: Replace fixed shapes with Flex for 30-50% savings
Arm Instance Savings (Generous Free Tier)
AMD instance: VM.Standard.E4.Flex (1 OCPU) = $0.03/hr
Arm instance: VM.Standard.A1.Flex (1 OCPU) = $0.01/hr (67% cheaper)
Always-Free Arm: 4 OCPUs free forever!
Use case: Web servers, CI/CD runners, dev environments
Limitation: ARM64 only (not all apps compatible)
Gotcha: Free tier is A1 shapes only, newer A2 shapes are paid
Storage Tiering (Exact Prices)
| Tier | Cost/GB/Month | Use Case | Retrieval |
|---|---|---|---|
| Standard | $0.0255 | Active data, frequent access | Instant, free |
| Infrequent Access | $0.0125 (51% off) | Backups, logs (accessed monthly) | Instant, $0.01/GB |
| Archive | $0.0024 (91% off) | Compliance, long-term retention | 1 hour, $0.01/GB |
Lifecycle policy example:
Day 0-30: Standard ($0.0255/GB/mo)
Day 31-90: Infrequent ($0.0125/GB/mo)
Day 91+: Archive ($0.0024/GB/mo)
1 TB data for 1 year:
Without tiering: $0.0255 × 1000 × 12 = $306/year
With tiering: $0.0255 × 1000 × 1 + $0.0125 × 1000 × 2 + $0.0024 × 1000 × 9 = $72/year
Savings: $234/year (76%)
Security Zones (OCI-Unique)
OCI Security Zones = Infrastructure-level policy enforcement:
Security Zone enforces:
✓ All storage encrypted
✓ No public buckets
✓ No internet gateways in VCN
✓ All databases private endpoint only
✓ Cloud Guard enabled
Enforcement: API rejects violating requests (preventive, not detective)
Example:
oci os bucket create --public-access-type ObjectRead
→ FAILS if compartment is in Security Zone
Use case: Production, PCI-DSS, healthcare (mandatory controls)
Gotcha: Security Zones can break existing automation (test in dev first)
Progressive Loading References
OCI Well-Architected Checklist
WHEN TO LOAD oci-well-architected-checklist.md:
- Running compliance checks against OCI tenancy
- Preparing for CIS OCI Foundations Benchmark audit
- Implementing automated security scanning
- Creating remediation scripts for common findings
- Setting up monitoring for drift detection
Do NOT load for:
- Quick anti-pattern reference (NEVER list above covers it)
- Architecture decisions (covered in this skill)
- Understanding OCI terminology (tables above)
Official Oracle Documentation Sources
Primary References (50+ official sources scraped):
- Well-Architected Framework for OCI
- OCI Architecture Center
- CIS OCI Foundations Benchmark
- Security Best Practices
- Compartment Design
- Network Architecture Patterns
Note: All anti-patterns, terminology mappings, and Always-Free limits in this skill are derived from official Oracle documentation and A-Team Oracle blog
When to Use This Skill
- Architecture design: Multi-AD patterns, compartment strategy, VCN sizing
- Migration from AWS/Azure: Terminology mapping, anti-pattern avoidance
- Cost optimization: Free tier planning, Flex shapes, storage tiering
- Security: Cloud Guard tuning, Security Zones, NSG vs Security Lists
- Production readiness: SLA requirements, HA patterns, fault tolerance
FAQ
What does the best-practices skill do?
Use when architecting OCI solutions, migrating from AWS/Azure, designing multi-AD deployments, or avoiding common OCI anti-patterns. Covers VCN sizing mistakes, Cloud Guard gotchas, free tier specifics, OCI terminology confusion, and multi-AD patterns.
How do I install best-practices?
Run npx skills add https://github.com/acedergren/oci-agent-skills --skill best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/best-practices/ (personal) or .claude/skills/best-practices/ (project).
Which AI agents can use best-practices?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is best-practices safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains best-practices?
It is published by acedergren in acedergren/oci-agent-skills. It has 113 recorded installs.
More from acedergren/oci-agent-skills
monitoring-operations
acedergren/oci-agent-skills
Use when setting up metrics, alarms, or troubleshooting missing data in OCI Monitoring. Covers metric namespace confusion, alarm threshold gotchas, log collection setup, and common monitoring gaps.
oracle-dba
acedergren/oci-agent-skills
Use when managing Oracle Autonomous Database on OCI, troubleshooting performance issues, optimizing costs, or implementing HA/DR. Covers ADB-specific gotchas, cost traps, SQLID debugging workflows, auto-scaling behavior, and version differences (19c/21c/23ai/26ai).
networking-management
acedergren/oci-agent-skills
Use when designing OCI networks, troubleshooting connectivity, optimizing egress costs, or configuring VCN security. Covers Service Gateway cost savings, VCN CIDR immutability, Security List vs NSG tradeoffs, VCN peering limitations, and Load Balancer subnet requirements.
compute-management
acedergren/oci-agent-skills
Use when launching OCI compute instances, troubleshooting out-of-capacity or boot failures, optimizing compute costs, or handling instance lifecycle. Covers shape selection, capacity planning, service limits, and production incident resolution.
database-management
acedergren/oci-agent-skills
Use when creating Autonomous Databases, troubleshooting connection failures, managing PDBs, or optimizing database costs. Covers connection string confusion, password validation errors, stop/start cost traps, clone type selection, and backup retention gotchas.
infrastructure-as-code
acedergren/oci-agent-skills
Use when writing Terraform for OCI, troubleshooting provider errors, managing state files, or implementing Resource Manager stacks. Covers terraform-provider-oci gotchas, resource lifecycle anti-patterns, state management mistakes, authentication issues, and OCI Landing Zones.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.