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、超时设置