Skip to main content
skill CX Codex

infrastructure-as-code — Claude Code skill for OCI Terraform

The infrastructure-as-code Claude Code skill helps write Terraform for OCI and diagnose provider errors. It applies to state management, Resource Manager stacks, and OCI Landing Zones.

MIT 106 installs ★ 22 updated 2026-04-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add acedergren/oci-agent-skills --skill infrastructure-as-code -a claude-code
Open on GitHub

What infrastructure-as-code does

The skill gives OCI-specific Terraform guidance, covering terraform-provider-oci quirks, state management mistakes, and resource lifecycle traps. It also addresses authentication and Resource Manager stacks.

For standard infrastructure, it points to official OCI Landing Zone modules; custom Terraform fits application-specific resources or extensions to those modules. Examples cover protecting critical resources with lifecycle, choosing for_each over count, and storing state in OCI Object Storage. When Terraform runs on OCI Compute, the instance must be in a dynamic group first or authentication fails.

What it helps with

  • diagnose an OCI Terraform provider error
  • choose a shared Terraform state setup for a team
  • guard a critical resource against accidental deletion
  • replace a hardcoded OCID with a variable or data source
  • configure Terraform authentication on OCI Compute

Example prompts for the agent

  • Help me write Terraform for an OCI network using Landing Zone modules.
  • Diagnose this terraform-provider-oci authentication error on OCI Compute.
  • Check this Terraform for accidental database deletion and state management mistakes.

How to install infrastructure-as-code

1Skills CLI (Vercel)

npx skills add acedergren/oci-agent-skills --skill infrastructure-as-code -a claude-code

2Manually: put the files in place

~/.claude/skills/infrastructure-as-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/infrastructure-as-code/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about infrastructure-as-code

How do I install infrastructure-as-code in Claude Code?

Run npx skills add acedergren/oci-agent-skills --skill infrastructure-as-code -a claude-code. The skill file is placed at ~/.claude/skills/infrastructure-as-code/SKILL.md.

What does infrastructure-as-code do?

It provides OCI-focused help with writing and troubleshooting Terraform, managing state, and implementing Resource Manager stacks. Its guidance covers provider quirks and resource lifecycle pitfalls.

What is needed to authenticate Terraform on OCI Compute?

Add the instance to a dynamic group before running Terraform. Set auth = "InstancePrincipal" in the provider configuration and configure the dynamic group matching rule and IAM policy.

Source text

SKILL.md · MIT
---
name: infrastructure-as-code
description: 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.
license: MIT
metadata:
  author: alexander-cedergren
  version: "2.0.0"
---

# OCI Infrastructure as Code - Expert Knowledge

## 🏗️ IMPORTANT: Use OCI Landing Zone Terraform Modules

### 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

---

## ⚠️ 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 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 Do This

❌ **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
}
```

## OCI Provider Gotchas

### 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 = '<compartment-ocid>'}"

# 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.

## State Management Anti-Patterns

### 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 <resource_type>.<name> <ocid>
```

**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

## Resource Lifecycle Traps

### 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"
  }
}
```

## OCI Landing Zones

**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

## Cost Optimization for IaC

### 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

## Progressive Loading References

### 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)

---

## When to Use This Skill

- 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

© alexander-cedergren · MIT · acedergren/oci-agent-skills

Similar skills

All skills for DevOps and infrastructure →
terraform-data-engineering-infrastructure reason-machines terraform-data-engineering-infrastructure is a Claude Code skill for defining AWS infrastructure for data engineering with Terraform. It activates on requests to provision resources for data pipelines and analytics workloads. CX Codex +1 1,800installs terraform-infrastructure-as-code manutej terraform-infrastructure-as-code equips your coding agent to structure Terraform manifests, configure cloud providers, and manage remote state. Useful when spinning up infrastructure with HCL. CX Codex +1 455installs auditing-terraform-infrastructure-for-security mahipal auditing-terraform-infrastructure-for-security guides AI assistants through auditing Terraform code with Checkov, tfsec, Terrascan, and OPA. Catches public access, lax IAM rules, and missing encryption before apply. CX Codex +1 279installs oci oracle oci — a skill for Oracle Cloud Infrastructure tasks: setting up OKE clusters, writing Terraform for IAM, Exadata, networking, Security Zones, deploying Functions, configuring IoT Platform, and building Enterprise AI workflows. CX Codex +1 598installs oracle-cloud DauQuangThanh Guides Oracle Cloud Infrastructure architecture, generates OCI Terraform configurations, and assists with OKE and Autonomous Database setups. CX Codex +1 152installs import-infrastructure-as-code official github import-infrastructure-as-code turns a live Azure subscription into Terraform built on Azure Verified Modules, with discovery, dependency mapping and the docs to back it up. CX Codex +1 6,900installs

From the same set9

monitoring-operations monitoring-operations — a skill for setting up OCI Monitoring metrics and alarms, and for figuring out why data stops showing up. Useful when an alarm stays silent or a metric disappears. CX Codex +1 1,400installs oracle-dba oracle-dba guides Oracle Autonomous Database administration on OCI, covering SQL_ID query tuning, wait events diagnosis, and cloud cost traps. CX Codex +1 145installs networking-management The networking-management skill guides OCI network design, connectivity debugging, VCN security, and egress routing decisions for agents working in infrastructure repositories. CX Codex +1 130installs best-practices best-practices — an OCI architecture skill: sizes VCNs you won't have to rebuild, keeps subnets regional, and warns where Cloud Guard auto-fixes bite. CX Codex +1 121installs compute-management compute-management — an OCI Compute skill for the agent: shape choice, service limits, instance costs and what to do when a launch fails. CX Codex +1 118installs database-management database-management — a skill for OCI Autonomous Database work: which connection service name to pick, why a password fails validation, what a stopped database still costs. CX Codex +1 108installs finops-cost-optimization The finops-cost-optimization Claude Code skill analyzes OCI spending and points out common sources of waste. It activates for bill investigations, budget planning, and cloud cost reviews. CX Codex +1 104installs iam-identity-management The iam-identity-management Claude Code skill covers OCI IAM policies and permission errors. It activates for dynamic group setup and IDCS integration work. CX Codex +1 104installs

Project sponsors

Companies that keep this analytics open