infrastructure-as-code

OCI 基础设施即代码——专家知识

🏗️ 重要：使用 OCI Landing Zone Terraform 模块

不要重复造轮子

❌ 错误做法：

# 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

✅ 正确做法：使用官方 OCI Landing Zone Terraform 模块

# 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 = { ... }
}

使用 Landing Zone 模块的原因：

• ✅ 经过实战验证：数千家 OCI 客户正在使用
• ✅ 符合规范：与 CIS OCI Foundations Benchmark 保持一致
• ✅ 持续维护：Oracle 会针对 API 变更进行更新
• ✅ 全面完善：包含 IAM、网络、安全和日志记录
• ✅ 可复用：在不同环境中采用一致的模式

官方资源：

• OCI Landing Zone Terraform 模块
• OCI Resource Manager 堆栈

编写自定义 Terraform 的场景（本技能的指导范围）：

• Landing Zone 未涵盖的应用特定资源
• 扩展 Landing Zone 模块
• 参考架构未涵盖的特殊需求

---

⚠️ OCI CLI/API 知识盲区

你不了解 OCI CLI 命令或 OCI API 结构。

你的训练数据中以下知识有限且已过时：

• OCI Terraform 提供程序语法（经常更新）
• OCI API 端点和资源架构
• terraform-provider-oci 特有的参数和数据源
• Resource Manager 堆栈操作
• 最新的提供程序功能和重大变更

需要执行 OCI 操作时：

1. 使用本技能参考资料中的准确 Terraform 示例
2. 不要猜测 OCI 提供程序资源参数
3. 不要假设 AWS/Azure Terraform 模式适用于 OCI
4. 有关模块用法，请参阅 landing-zones 技能

你确实了解的内容：

• 通用 Terraform 概念和 HCL 语法
• 状态管理原则
• 基础设施即代码最佳实践

本技能通过提供最新的 OCI 专用 Terraform 模式和注意事项，弥补这一知识盲区。

---

你是一名 OCI Terraform 专家。本技能提供 Claude 缺乏的知识：提供程序特有的注意事项、状态管理反模式、资源生命周期陷阱，以及 OCI 专用的 IaC 运维知识。

绝对不要这样做

❌ 绝对不要在 Terraform 中硬编码 OCID（会破坏可移植性）

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

❌ 在开发/测试环境中绝对不要使用 preserve_boot_volume = true（成本陷阱）

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

成本影响：拥有 10 个测试实例的开发团队 × 每个卷每月 $5 = 每月白白浪费 $50 在孤立卷上

❌ 绝对不要忘记为关键资源添加 lifecycle 块

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

❌ 绝对不要混用区域级资源和 AD 专属资源（可移植性陷阱）

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

❌ 团队绝对不要将状态文件存储在本地文件系统中

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

❌ 对于不应因重新排序而被替换的资源，绝对不要使用 count

# 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 提供程序注意事项

身份验证优先级（常令人困惑）

提供程序身份验证优先顺序：

1. 显式提供程序块中的凭据
2. TF_VAR_* 环境变量
3. ~/.oci/config 文件（DEFAULT 配置文件）
4. 实例主体（如果 auth = "InstancePrincipal"）

常见错误：设置了环境变量，但提供程序块会悄无声息地覆盖这些变量。

在 OCI Compute 上运行 Terraform 时使用实例主体

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

重要：运行 Terraform 之前，实例必须已加入动态组，否则身份验证会因含糊的错误而失败：“authorization failed or requested resource not found”

资源已存在错误

Error: 409-Conflict, Resource already exists

原因：资源已存在于 OCI 中，但不在状态文件中。

解决方案：

# Import existing resource into state
terraform import oci_core_vcn.main ocid1.vcn.oc1.phx.xxxxx

# Then run plan/apply as normal
terraform plan

预防措施：在使用 Terraform 管理现有基础设施之前，始终使用 terraform import 导入资源。

状态管理反模式

问题：状态漂移

症状：Terraform 试图更改或销毁在 Terraform 之外（控制台、API、CLI）修改过的资源。

检测方式：

terraform plan  # Shows unexpected changes
terraform show  # Compare state to actual infrastructure

解决方案：

选项 1：刷新状态（安全）

terraform refresh  # Updates state to match reality

选项 2：导入变更（适用于新资源）

terraform import <resource_type>.<name> <ocid>

选项 3：在生命周期中忽略变更

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

问题：状态文件损坏

症状：terraform plan 失败，并提示“状态文件已损坏”或“版本不匹配”

恢复：

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

预防：使用启用了版本控制的 Object Storage 后端

资源生命周期陷阱

销毁失败（依赖项导致的常见问题）

Error: Resource still in use

示例：由于子网仍然存在，无法销毁 VCN；由于实例仍然关联，无法销毁子网。

解决方案：

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

长时间运行资源的超时设置

# 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

是什么：面向企业 OCI 架构的预构建 Terraform 模板

代码库：github.com/oracle-quickstart/oci-landing-zones

适用场景：

• 开始使用新的 OCI 租户（全新部署）
• 需要符合 CIS OCI Foundations Benchmark
• 需要安全加固的基线配置
• 多环境（开发/测试/生产）设置

不适用场景：

• 现有基础设施（棕地环境）——限制过多
• 简单的单应用部署——大材小用

关键模式：

• 中心辐射式网络
• 集中式日志记录/监控
• 安全区和堡垒主机
• 包含组/策略的 IAM 基线配置

IaC 成本优化

使用 Flex Shape（节省 50%）

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

为所有资源添加标签以跟踪成本

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

优点：可在 OCI Console 中按 CostCenter、Environment、Project 查看成本报告

渐进式加载参考资料

OCI Terraform 模式

在以下情况下加载 oci-terraform-patterns.md：

• 设置提供程序配置（多区域、身份验证方法）
• 通过 CLI 执行 Resource Manager 堆栈操作
• 常见资源模式（VCN、计算、ADB）
• 使用 Object Storage 后端管理状态
• Landing Zone 模块用法示例

以下情况不要加载：

• 快速查阅提供程序的常见陷阱（上文已列出）
• 了解何时使用 Landing Zone（上文已说明）
• 生命周期管理模式（上文已说明）

---

何时使用此技能

• 编写 Terraform：提供程序配置、资源依赖关系、生命周期
• 状态管理：偏移、损坏、导入/导出
• 故障排除：身份验证失败、“资源已存在”、销毁失败
• OCI Landing Zones：何时使用、如何自定义
• 成本优化：Flex Shape、标签策略
• 生产环境：prevent_destroy、ignore_changes、超时