跳转至

Python libterraform

Python libterraform logo

libterraform 是 Terraform 的 Python 绑定。它把 Terraform 打包为共享库， 并提供 Python API 来执行 Terraform CLI 命令、解析 Terraform 配置目录。

提供能力

  • TerraformCommand：从 Python 调用 Terraform 命令。
  • AsyncTerraformCommand：在 asyncio 应用中等待 Terraform 命令，同时避免阻塞 event loop。
  • TerraformConfig：把 .tf 和 .tf.json 文件加载为 Terraform 内部模块表示。
  • 预构建 wheel 内包含 Terraform 共享库，调用方通常不需要在 PATH 中额外安装 terraform 可执行文件。

从这里开始

版本对应关系

libterraform Terraform
0.15.3 1.15.5
0.14.0 1.14.9
0.13.0 1.13.5
0.12.0 1.12.2
0.11.0 1.11.4
0.10.0 1.10.5
0.9.0 1.9.8
0.8.2 1.8.4
0.7.0 1.6.6
0.6.0 1.5.7
0.5.0 1.3.0
0.4.0 1.2.2
0.3.1 1.1.7

运行约束

TerraformCommand 和 AsyncTerraformCommand 默认使用进程隔离执行。Terraform 仍使用 当前工作目录、stdio、checkpoint 状态和 plugin client 清理等进程级全局状态，因此把 CLI 放到受控 worker 进程中运行，可以避免这些状态泄漏到调用方进程。

只有在明确需要当前进程后端时，才使用 backend="thread"。该路径开销更低，并会在每次 调用结束后恢复全局状态；但命令运行期间，同一 Python 进程中的其他代码仍可能观察到 Terraform 临时修改后的全局状态。如果需要复用 worker 进程或让独立 Terraform 操作真正 并行执行，请使用 TerraformPool。

Terraform 操作仍可能影响真实基础设施，因此执行 apply、destroy、状态命令、 导入和测试时，应保持与直接使用 Terraform CLI 相同的谨慎程度。