Back to Details

infrastructure-as-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OCI Infrastructure as Code - Expert Knowledge

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

🏗️ IMPORTANT: Use OCI Landing Zone Terraform Modules

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

Do NOT Reinvent the Wheel

切勿重复造轮子

❌ WRONG Approach:
hcl
undefined
❌ 错误做法：
hcl
undefined

Writing Terraform from scratch for every resource

为每个资源从零开始编写Terraform代码

resource "oci_identity_compartment" "prod" { ... } resource "oci_core_vcn" "main" { ... } resource "oci_identity_policy" "policies" { ... }
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

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

```hcl

Use official OCI Landing Zone modules

使用官方OCI Landing Zone模块

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

---
module "landing_zone" { source = "oracle-terraform-modules/landing-zone/oci" version = "~> 2.0"

基础设施配置

compartments_configuration = { ... } network_configuration = { ... } security_configuration = { ... } }

**为何使用Landing Zone模块：**
- ✅ **久经考验**：已被数千家OCI客户使用
- ✅ **合规**：符合CIS OCI基础基准要求
- ✅ **持续维护**：Oracle会针对API变更进行更新
- ✅ **全面覆盖**：包含IAM、网络、安全、日志功能
- ✅ **可复用**：在多环境中保持一致的架构模式

**官方资源：**
- [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)

**何时编写自定义Terraform代码**（本技能提供指导）：
- Landing Zone未覆盖的特定应用资源
- 扩展Landing Zone模块
- 参考架构未包含的特殊需求

---

⚠️ OCI CLI/API Knowledge Gap

⚠️ OCI CLI/API知识缺口

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.
你不了解OCI CLI命令或OCI API结构。
你的训练数据在以下方面的知识有限且过时：
  • OCI Terraform provider语法（更新频繁）
  • OCI API端点和资源架构
  • terraform-provider-oci特定参数和数据源
  • Resource Manager堆栈操作
  • 最新提供商功能和破坏性变更
当需要执行OCI操作时：
  1. 使用本技能参考资料中的精确Terraform示例
  2. 切勿猜测OCI provider资源参数
  3. 切勿假设AWS/Azure的Terraform模式适用于OCI
  4. 参考landing-zones技能获取模块使用方法
你已掌握的内容：
  • 通用Terraform概念和HCL语法
  • 状态管理原则
  • 基础设施即代码最佳实践
本技能通过提供当前OCI特定的Terraform模式和常见陷阱来弥补这一缺口。
你是一名OCI Terraform专家。本技能补充了Claude缺失的知识：提供商特定陷阱、状态管理反模式、资源生命周期陷阱以及OCI特定IaC运维知识。

NEVER Do This

绝对禁止的操作

❌ NEVER hardcode OCIDs in Terraform (breaks portability)
hcl
undefined
❌ 绝对不要在Terraform中硬编码OCID（会破坏可移植性）
hcl
undefined

WRONG - breaks when moving between regions/compartments

错误 - 在区域/Compartment间迁移时会失效

resource "oci_core_instance" "web" { compartment_id = "ocid1.compartment.oc1..aaaaaa..." # Hardcoded! subnet_id = "ocid1.subnet.oc1.phx.bbbbbb..." # Hardcoded! }
resource "oci_core_instance" "web" { compartment_id = "ocid1.compartment.oc1..aaaaaa..." # 硬编码！ subnet_id = "ocid1.subnet.oc1.phx.bbbbbb..." # 硬编码！ }

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
resource "oci_core_instance" "web" { compartment_id = var.compartment_ocid subnet_id = data.oci_core_subnet.existing.id }

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

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

错误 - 销毁实例时会遗留引导卷（每个实例每月花费50美元以上）

resource "oci_core_instance" "dev" { preserve_boot_volume = true # Default behavior! }
resource "oci_core_instance" "dev" { preserve_boot_volume = true # 默认行为！ }

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
resource "oci_core_instance" "dev" { preserve_boot_volume = false }

**成本影响**：拥有10个测试实例的开发团队 × 每个卷每月5美元 = 每月浪费50美元在遗留卷上

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

WRONG - accidental destroy can delete production database

错误 - 意外销毁可能会删除生产数据库

resource "oci_database_autonomous_database" "prod" {

No protection!

}
resource "oci_database_autonomous_database" "prod" {

无保护！

}

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
resource "oci_database_autonomous_database" "prod" { lifecycle { prevent_destroy = true ignore_changes = [defined_tags] # 忽略控制台的标签变更 } }

❌ **绝对不要混合使用区域资源和AD特定资源（可移植性陷阱）**
```hcl

WRONG - hardcoded AD breaks multi-region deployment

错误 - 硬编码AD会破坏多区域部署

resource "oci_core_instance" "web" { availability_domain = "fMgC:US-ASHBURN-AD-1" # Tenant-specific! }
resource "oci_core_instance" "web" { availability_domain = "fMgC:US-ASHBURN-AD-1" # 租户特定！ }

RIGHT - query AD dynamically

正确 - 动态查询AD

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

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

WRONG - no locking, no collaboration

错误 - 无锁定、无法协作

terraform { backend "local" {} }
terraform { backend "local" {} }

RIGHT - use OCI Object Storage with locking

正确 - 使用带锁定功能的OCI对象存储

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

WRONG - reordering list recreates ALL resources

错误 - 列表重新排序会重建所有资源

resource "oci_core_instance" "web" { count = length(var.instance_names) display_name = var.instance_names[count.index] }
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"]

如果instance_names从["web1", "web2", "web3"]变为["web0", "web1", "web2", "web3"]

Terraform RECREATES all instances!

Terraform会重建所有实例！

RIGHT - use for_each with stable keys

正确 - 使用带稳定键的for_each

resource "oci_core_instance" "web" { for_each = toset(var.instance_names) display_name = each.value }
undefined
resource "oci_core_instance" "web" { for_each = toset(var.instance_names) display_name = each.value }
undefined

OCI Provider Gotchas

OCI Provider常见陷阱

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.
提供商认证优先级：
  1. 显式提供商块凭证
  2. TF_VAR_*
    环境变量
  3. ~/.oci/config
    文件（DEFAULT配置文件）
  4. Instance Principal（如果
    auth = "InstancePrincipal"
    ）
常见错误：设置了环境变量，但提供商块会静默覆盖它们。

Instance Principal for Terraform on OCI Compute

在OCI Compute上使用Instance Principal运行Terraform

hcl
undefined
hcl
undefined

In provider.tf

在provider.tf中

provider "oci" { auth = "InstancePrincipal" region = var.region }
provider "oci" { auth = "InstancePrincipal" region = var.region }

Dynamic group matching rule:

动态组匹配规则：

"ALL {instance.compartment.id = '<compartment-ocid>'}"

"ALL {instance.compartment.id = '<compartment-ocid>'}"

IAM policy:

IAM策略：

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

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

**关键提示**：实例必须在Terraform运行前加入动态组，否则认证会失败并显示模糊错误：“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
undefined
Error: 409-Conflict, Resource already exists
原因：资源在OCI中存在，但未在状态文件中记录。
解决方案：
bash
undefined

Import existing resource into state

将现有资源导入状态

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

Then run plan/apply as normal

然后正常执行plan/apply

terraform plan

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

**预防措施**：在使用Terraform管理现有基础设施前，务必使用`terraform import`。

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
}
症状：Terraform想要修改/销毁那些通过Terraform之外的方式（控制台、API、CLI）修改过的资源。
检测方法：
bash
terraform plan  # 显示意外变更
terraform show  # 对比状态与实际基础设施
解决方案：
选项1：刷新状态（安全）
bash
terraform refresh  # 更新状态以匹配实际情况
选项2：导入变更（如果有新资源）
bash
terraform import <resource_type>.<name> <ocid>
选项3：在lifecycle中忽略变更
hcl
lifecycle {
  ignore_changes = [defined_tags, freeform_tags]  # 忽略控制台的标签编辑
}

Problem: State File Corruption

问题：状态文件损坏

Symptoms: 
terraform plan
fails with "state file corrupted" or "version mismatch"
Recovery:
bash
undefined
症状：
terraform plan
失败并显示“state file corrupted”或“version mismatch”
恢复方法：
bash
undefined

1. Make backup

1. 制作备份

cp terraform.tfstate terraform.tfstate.backup
cp terraform.tfstate terraform.tfstate.backup

2. Try state repair

2. 尝试修复状态

terraform state pull > recovered.tfstate mv recovered.tfstate terraform.tfstate
terraform state pull > recovered.tfstate mv recovered.tfstate terraform.tfstate

3. If that fails, restore from Object Storage versioning

3. 如果失败，从对象存储版本控制恢复

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
undefined
Error: Resource still in use
示例：无法销毁VCN因为子网仍存在，无法销毁子网因为实例仍附着在上面。
解决方案：
bash
undefined

1. Visualize dependencies

1. 可视化依赖关系

terraform graph | dot -Tpng > graph.png
terraform graph | dot -Tpng > graph.png

2. Destroy in reverse order

2. 按逆序销毁

terraform destroy -target=oci_core_instance.web terraform destroy -target=oci_core_subnet.private terraform destroy -target=oci_core_vcn.main
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:

或显式使用depends_on：

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

}
undefined
resource "oci_core_vcn" "main" {

...

}
resource "oci_core_subnet" "private" { vcn_id = oci_core_vcn.main.id

通过vcn_id引用隐式依赖

}
undefined

Timeouts for Long-Running Resources

长运行资源的超时设置

hcl
undefined
hcl
undefined

Database provisioning takes 15-30 minutes

数据库配置需要15-30分钟

resource "oci_database_autonomous_database" "prod" {

... configuration ...

timeouts { create = "60m" # Default 20m often not enough update = "60m" delete = "30m" } }
resource "oci_database_autonomous_database" "prod" {

... 配置 ...

timeouts { create = "60m" # 默认20分钟通常不够 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" } }
undefined
resource "oci_core_instance" "web" {

... 配置 ...

timeouts { create = "30m" # 允许在“容量不足”时重试 } }
undefined

OCI Landing Zones

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
定义：为企业OCI架构预构建的Terraform模板
仓库：
github.com/oracle-quickstart/oci-landing-zones
适用场景：
  • 新建OCI租户（绿地项目）
  • 需要符合CIS OCI基础基准要求
  • 想要安全加固的基线
  • 多环境（开发/测试/生产）部署
不适用场景：
  • 棕地项目（现有基础设施）- 过于主观
  • 简单单应用部署 - 大材小用
核心模式：
  • 中心辐射式网络
  • 集中式日志/监控
  • 安全区域和堡垒机
  • 带用户组/策略的IAM基线

Cost Optimization for IaC

IaC成本优化

Use Flex Shapes (50% savings)

使用Flex形状（节省50%成本）

hcl
undefined
hcl
undefined

EXPENSIVE - fixed shape

昂贵 - 固定形状

resource "oci_core_instance" "web" { shape = "VM.Standard2.4" # 4 OCPUs, 60GB RAM, $218/month }
resource "oci_core_instance" "web" { shape = "VM.Standard2.4" # 4个OCPU，60GB内存，每月218美元 }

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)

}
undefined
resource "oci_core_instance" "web" { shape = "VM.Standard.E4.Flex" shape_config { ocpus = 4 memory_in_gbs = 60 }

成本：(4 × $0.03 + 60 × $0.0015) × 730 = 每月153美元（节省30%）

}
undefined

Tag Everything for Cost Tracking

为所有资源打标签以追踪成本

hcl
undefined
hcl
undefined

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
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控制台中按成本中心、环境、项目进行成本报告

Progressive Loading References

渐进式加载参考资料

OCI Terraform Patterns

OCI Terraform模式

WHEN TO LOAD 
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)
何时加载 
oci-terraform-patterns.md
：
  • 设置提供商配置（多区域、认证方法）
  • 通过CLI执行Resource Manager堆栈操作
  • 常见资源模式（VCN、计算、ADB）
  • 使用对象存储后端进行状态管理
  • Landing Zone模块使用示例
请勿加载：
  • 快速查阅提供商常见陷阱（上述绝对禁止列表已覆盖）
  • 了解何时使用Landing Zone（上述内容已覆盖）
  • 生命周期管理模式（上述内容已覆盖）

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
  • 编写Terraform代码：提供商配置、资源依赖、生命周期
  • 状态管理：漂移、损坏、导入/导出
  • 故障排查：认证失败、“资源已存在”、销毁失败
  • OCI Landing Zones：何时使用、如何自定义
  • 成本优化：Flex形状、标签策略
  • 生产环境：prevent_destroy、ignore_changes、超时设置