infrastructure-as-code

Do NOT Reinvent the Wheel

❌ WRONG Approach:

```hcl

# Writing Terraform from scratch for every resource

resource "oci_identity_compartment" "prod" { ... }

resource "oci_core_vcn" "main" { ... }

resource "oci_identity_policy" "policies" { ... }

# Result: Unmaintainable, inconsistent, no governance

```

✅ RIGHT Approach: Use Official OCI Landing Zone Terraform Modules

```hcl

# Use official OCI Landing Zone modules

module "landing_zone" {

source = "oracle-terraform-modules/landing-zone/oci"

version = "~> 2.0"

# Infrastructure configuration

compartments_configuration = { ... }

network_configuration = { ... }

security_configuration = { ... }

}

```

Why Use Landing Zone Modules:

• ✅ Battle-tested: Thousands of OCI customers
• ✅ Compliant: CIS OCI Foundations Benchmark aligned
• ✅ Maintained: Oracle updates for API changes
• ✅ Comprehensive: Includes IAM, networking, security, logging
• ✅ Reusable: Consistent patterns across environments

Official Resources:

• [OCI Landing Zone Terraform Modules](https://github.com/oracle-terraform-modules/terraform-oci-landing-zones)
• [OCI Resource Manager Stacks](https://docs.oracle.com/en-us/iaas/Content/ResourceManager/Tasks/deployments.htm)

When to Write Custom Terraform (this skill's guidance):

• Application-specific resources not covered by landing zone
• Extending landing zone modules
• Special requirements not in reference architecture

---

You don't know OCI CLI commands or OCI API structure.

Your training data has limited and outdated knowledge of:

• OCI Terraform provider syntax (updates frequently)
• OCI API endpoints and resource schemas
• terraform-provider-oci specific arguments and data sources
• Resource Manager stack operations
• Latest provider features and breaking changes

When OCI operations are needed:

1. Use exact Terraform examples from this skill's references
2. Do NOT guess OCI provider resource arguments
3. Do NOT assume AWS/Azure Terraform patterns work in OCI
4. Reference landing-zones skill for module usage

What you DO know:

• General Terraform concepts and HCL syntax
• State management principles
• Infrastructure as Code best practices

This skill bridges the gap by providing current OCI-specific Terraform patterns and gotchas.

---

You are an OCI Terraform expert. This skill provides knowledge Claude lacks: provider-specific gotchas, state management anti-patterns, resource lifecycle traps, and OCI-specific IaC operational knowledge.

❌ NEVER hardcode OCIDs in Terraform (breaks portability)

```hcl

# WRONG - breaks when moving between regions/compartments

resource "oci_core_instance" "web" {

compartment_id = "ocid1.compartment.oc1..aaaaaa..." # Hardcoded!

subnet_id = "ocid1.subnet.oc1.phx.bbbbbb..." # Hardcoded!

}

# RIGHT - use variables or data sources

resource "oci_core_instance" "web" {

compartment_id = var.compartment_ocid

subnet_id = data.oci_core_subnet.existing.id

}

```

❌ NEVER use preserve_boot_volume = true in dev/test (cost trap)

```hcl

# WRONG - orphans boot volumes when instance destroyed ($50+/month per instance)

resource "oci_core_instance" "dev" {

preserve_boot_volume = true # Default behavior!

}

# RIGHT - explicit cleanup in dev/test

resource "oci_core_instance" "dev" {

preserve_boot_volume = false

}

```

Cost impact: Dev team with 10 test instances × $5/volume/month = $50/month wasted on orphaned volumes

❌ NEVER forget lifecycle blocks for critical resources

```hcl

# WRONG - accidental destroy can delete production database

resource "oci_database_autonomous_database" "prod" {

# No protection!

}

# RIGHT - prevent accidental destruction

resource "oci_database_autonomous_database" "prod" {

lifecycle {

prevent_destroy = true

ignore_changes = [defined_tags] # Ignore tag changes from console

}

}

```

❌ NEVER mix regional and AD-specific resources (portability trap)

```hcl

# WRONG - hardcoded AD breaks multi-region deployment

resource "oci_core_instance" "web" {

availability_domain = "fMgC:US-ASHBURN-AD-1" # Tenant-specific!

}

# RIGHT - query AD 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

}

```

❌ NEVER store state file in local filesystem for teams

```hcl

# WRONG - no locking, no collaboration

terraform {

backend "local" {}

}

# RIGHT - use OCI Object Storage with locking

terraform {

backend "s3" {

bucket = "terraform-state"

key = "prod/terraform.tfstate"

region = "us-phoenix-1"

endpoint = "https://namespace.compat.objectstorage.us-phoenix-1.oraclecloud.com"

skip_region_validation = true

skip_credentials_validation = true

skip_metadata_api_check = true

use_path_style = true

}

}

```

❌ NEVER use count for resources that shouldn't be replaced on reorder

```hcl

# WRONG - reordering list recreates ALL resources

resource "oci_core_instance" "web" {

count = length(var.instance_names)

display_name = var.instance_names[count.index]

}

# If instance_names changes from ["web1", "web2", "web3"] to ["web0", "web1", "web2", "web3"]

# Terraform RECREATES all instances!

# RIGHT - use for_each with stable keys

resource "oci_core_instance" "web" {

for_each = toset(var.instance_names)

display_name = each.value

}

```

Authentication Hierarchy (Often Confusing)

Provider authentication precedence:

1. Explicit provider block credentials
2. TF_VAR_* environment variables
3. ~/.oci/config file (DEFAULT profile)
4. Instance Principal (if auth = "InstancePrincipal")

Common mistake: Setting environment variables but provider block overrides them silently.

Instance Principal for Terraform on OCI Compute

```hcl

# In provider.tf

provider "oci" {

auth = "InstancePrincipal"

region = var.region

}

# Dynamic group matching rule:

# "ALL {instance.compartment.id = ''}"

# IAM policy:

# "Allow dynamic-group terraform-instances to manage all-resources in tenancy"

```

Critical: Instance must be in dynamic group BEFORE Terraform runs, or authentication fails with cryptic error: "authorization failed or requested resource not found"

Resource Already Exists Errors

```

Error: 409-Conflict, Resource already exists

```

Cause: Resource exists in OCI but not in state file.

Solution:

```bash

# Import existing resource into state

terraform import oci_core_vcn.main ocid1.vcn.oc1.phx.xxxxx

# Then run plan/apply as normal

terraform plan

```

Prevention: Always use terraform import for existing infrastructure before managing with Terraform.

Problem: State Drift

Symptoms: Terraform wants to change/destroy resources that were modified outside Terraform (console, API, CLI).

Detection:

```bash

terraform plan # Shows unexpected changes

terraform show # Compare state to actual infrastructure

```

Solutions:

Option 1: Refresh state (safe)

```bash

terraform refresh # Updates state to match reality

```

Option 2: Import changes (if new resources)

```bash

terraform import .

```

Option 3: Ignore changes in lifecycle

```hcl

lifecycle {

ignore_changes = [defined_tags, freeform_tags] # Ignore console tag edits

}

```

Problem: State File Corruption

Symptoms: terraform plan fails with "state file corrupted" or "version mismatch"

Recovery:

```bash

# 1. Make backup

cp terraform.tfstate terraform.tfstate.backup

# 2. Try state repair

terraform state pull > recovered.tfstate

mv recovered.tfstate terraform.tfstate

# 3. If that fails, restore from Object Storage versioning

# Or reconstruct with imports (last resort)

```

Prevention: Use Object Storage backend with versioning enabled

Destroy Failures (Common with Dependencies)

```

Error: Resource still in use

```

Example: Can't destroy VCN because subnet still exists, can't destroy subnet because instances still attached.

Solution:

```bash

# 1. Visualize dependencies

terraform graph | dot -Tpng > graph.png

# 2. Destroy in reverse order

terraform destroy -target=oci_core_instance.web

terraform destroy -target=oci_core_subnet.private

terraform destroy -target=oci_core_vcn.main

# Or use depends_on explicitly:

resource "oci_core_vcn" "main" {

# ...

}

resource "oci_core_subnet" "private" {

vcn_id = oci_core_vcn.main.id

# depends_on is implicit via vcn_id reference

}

```

Timeouts for Long-Running Resources

```hcl

# Database provisioning takes 15-30 minutes

resource "oci_database_autonomous_database" "prod" {

# ... configuration ...

timeouts {

create = "60m" # Default 20m often not enough

update = "60m"

delete = "30m"

}

}

# Compute instance usually fast, but can timeout on capacity issues

resource "oci_core_instance" "web" {

# ... configuration ...

timeouts {

create = "30m" # Allow retries on "out of capacity"

}

}

```

What: Pre-built Terraform templates for enterprise OCI architectures

Repository: github.com/oracle-quickstart/oci-landing-zones

Use when:

• Starting new OCI tenancy (greenfield)
• Need CIS OCI Foundations Benchmark compliance
• Want security-hardened baseline
• Multi-environment (dev/test/prod) setup

DON'T use when:

• Brownfield (existing infrastructure) - too opinionated
• Simple single-app deployment - overkill

Key patterns:

• Hub-and-spoke networking
• Centralized logging/monitoring
• Security zones and bastion hosts
• IAM baseline with groups/policies

Use Flex Shapes (50% savings)

```hcl

# EXPENSIVE - fixed shape

resource "oci_core_instance" "web" {

shape = "VM.Standard2.4" # 4 OCPUs, 60GB RAM, $218/month

}

# CHEAPER - flexible shape

resource "oci_core_instance" "web" {

shape = "VM.Standard.E4.Flex"

shape_config {

ocpus = 4

memory_in_gbs = 60

}

# Cost: (4 × $0.03 + 60 × $0.0015) × 730 = $153/month (30% savings)

}

```

Tag Everything for Cost Tracking

```hcl

# Define locals for consistent tagging

locals {

common_tags = {

"CostCenter" = "Engineering"

"Environment" = var.environment

"ManagedBy" = "Terraform"

"Project" = var.project_name

}

}

resource "oci_core_instance" "web" {

freeform_tags = merge(

local.common_tags,

{

"Component" = "WebServer"

}

)

}

```

Benefit: Cost reporting by CostCenter, Environment, Project in OCI Console

OCI Terraform Patterns

WHEN TO LOAD [oci-terraform-patterns.md](references/oci-terraform-patterns.md):

• Setting up provider configuration (multi-region, auth methods)
• Resource Manager stack operations via CLI
• Common resource patterns (VCN, compute, ADB)
• State management with Object Storage backend
• Landing Zone module usage examples

Do NOT load for:

• Quick provider gotchas (NEVER list above)
• Understanding when to use Landing Zone (covered above)
• Lifecycle management patterns (covered above)

---

• Writing Terraform: provider configuration, resource dependencies, lifecycle
• State management: drift, corruption, import/export
• Troubleshooting: authentication failures, "resource already exists", destroy failures
• OCI Landing Zones: when to use, how to customize
• Cost optimization: Flex shapes, tagging strategies
• Production: prevent_destroy, ignore_changes, timeouts