terraform-sage

跨平台工具，简化Terraform部署

• 快速入门
• 常见问题解答
• 高级用法
• 项目结构
• 开发
• 许可协议

特性

• 基于模板的多环境工作方式
• 通过命令行界面（如Terraform一样）进行半自动化部署

要求

Terraform >= 0.11（旧版本未测试）

快速入门

1. 安装 Terraform。

2. 从 发布页面 下载根据所使用的操作系统相应的可执行文件/二进制文件。

3. 将可执行文件/二进制文件链接到操作系统，以便您可以在任何地方调用 terraform-sage

   • Linux / Mac OS

     将二进制文件移动到 /usr/local/bin 目录，然后重启终端

     mv ~/Downloads/terraform-sage /usr/local/bin
     

   • Windows

     1. 右键点击Windows标志并选择 系统 菜单项。
     2. 点击 高级系统设置 按钮。
     3. 点击 环境变量 按钮。
     4. 选择您的 PATH 变量并点击 编辑 按钮。
     5. 点击 新建 按钮。
     6. 添加 terraform-sage 可执行文件所在的文件路径。
     7. 点击几次 确定 按钮以应用更改。

4. 转到您的代码目录，并创建一个用于Terraform文件的目录。例如，我们可以将其命名为 terraform。

5. 在 terraform 目录中，创建 configs 目录。此目录将存储与每个环境相关联的所有必需的Terraform模块。因此，您将得到以下内容

   <sources>
   ├ docker
   ├ microservice
   └ terraform
     └ configs
       ├ dev
       │  ├ ... 
       │  └ variables.tf
       ├ staging
       │  ├ ...
       │  └ variables.tf
       └ production
          ├ ...
          └ variables.tf
   

   configs 目录是必需的，用于正确平稳地运行此包装器。 terraform-sage 将跟踪 configs 目录中定义的环境，并根据调用的Terraform命令执行相应的操作。

   附言。有关推荐项目结构的更多信息，请参阅 项目结构 部分。

6. 创建基础模板（建议命名为 main.tpl），该模板存储资源的主体定义和 Terraform 状态的后端存储。为了使编写基础模板更简单，建议您从 main.tf 模块开始，在那里描述您需要的一切，然后将其重命名为 main.tpl。在描述完所有资源/模块后，您需要指定一个可用的 后端存储 用于 Terraform 状态，然后将 {{CONFIG_NAME}} 字符串附加到键（这是 Terraform 状态的文件名），如下所示

   terraform {
     backend "s3" {
       bucket = "state-bucket"
       key    = "terraform/state-{{CONFIG_NAME}}.tfstate"
       region = "us-east-1"
     }
   }
   

   {{CONFIG_NAME}} 字符串用作模板参数，在调用 terraform-sage 命令时将替换为使用的环境名称。此功能将帮助我们处理不同的环境，而无需复制 main.tf 文件的源代码。

7. 然后，您可以使用以下命令代替直接调用 Terraform CLI

   terraform-sage init
   terraform-sage plan
   terraform-sage apply
   terraform-sage destroy
   terraform-sage output
   

   此外，CLI 还提供了两个额外的命令，用于生成 Terraform 的 main.tf 模块和检索可用环境的列表。

   terraform-sage generate
   terraform-sage list
   

   有关每个命令的接受参数和选项的更多信息，请使用 --help 选项调用任何所需的命令。

常见问题解答（F.A.Q.）

问：为什么编写了这个工具/包装器？
答：作为一个相当懒惰的开发者，我厌倦了在需要创建或更新现有环境中的某些内容时编写冗长的 Terraform 命令调用，指定使用的 *.tf / *.tfvars 模块。当开发人员使用不同的操作系统和“额外”脚本来简化他们的 Terraform 工作流程时，模块的混乱会增加。

问：如何传递 Terraform 命令（例如 terraform-sage apply）的额外参数？
答：对于这种情况，您需要在末尾附加 .，然后像使用实际的 Terraform CLI 一样指定参数列表，如下所示

terraform apply dev --dir=examples/approach_two . -var-file=my-variables.tf

高级用法

Terraform-sage 工具还提供了一种为每个使用环境定义附加上下文的方法。为此，您需要在根配置文件夹中创建一个名为 context.toml 的新文件。结果，我们将拥有以下项目结构

terraform
├ configs
│  ├ dev
│  │  ├ secrets.tf
│  │  └ variables.tf
│  ├ staging
│  │  ├ secrets.tf
│  │  └ variables.tf
│  └ production
│  │  ├ secrets.tf
│  │  └ variables.tf
│  └  context.toml
└ main.tpl

context.toml 文件包含模板引擎的占位符，该引擎用于生成 main.tf 文件。每个部分都有与您的环境文件夹相同的名称。在每一部分下，您需要指定键值对，这些键值对将在适当的上下文中使用。

以下是一些定义示例

[dev]
bucket_name = "dev"
profile = "aws-dev-account"

[product]
bucket_name = "prod"
profile = "aws-prod-account"

之后，您需要在 main.tpl 中适当的位置声明占位符，如下所示

provider "aws" {
  profile = "{{profile}}"
  region  = "us-east-1"
}

# ...

resource "aws_s3_bucket" "bucket" {
  bucket = "terraform-sage-bucket"
  acl    = "private"

  tags = {
    "Name": "{{bucket_name}}"
    "EnvironmentType" = "${var.environment}"
  }
}

然后您就可以出发了！只需调用 terraform-sage apply dev 命令（或任何适合您的命令）即可，无需进行任何其他更改。

项目结构

terraform-sage 应用程序依赖于特定的项目结构才能正常工作。因此，我建议开发者采取以下两种方式来组织自己的项目

• 方法 #1

  terraform
  ├ configs
  │  ├ dev
  │  │  ├ secrets.tf
  │  │  └ variables.tf
  │  ├ staging
  │  │  ├ secrets.tf
  │  │  └ variables.tf
  │  └ production
  │     ├ secrets.tf
  │     └ variables.tf
  ├ resources
  │  ├ rds
  │  │  ├ main.tf
  │  │  ├ output.tf
  │  │  └ variables.tf
  │  └ sqs
  │     ├ main.tf
  │     ├ output.tf
  │     └ variables.tf
  └ main.tpl
  

  优点

  • 依赖资源被分割成 Terraform 模块，因此更容易在其他项目中重用。
  • 更容易管理具有许多依赖项的项目。
  • main.tpl 文件相对较小，只包含最小量的代码

  缺点

  • 在从主可执行 Terraform 配置提供额外参数到依赖资源时，需要更多的模板代码。

• 方法 #2

  terraform
  ├ configs
  │  ├ dev
  │  │  ├ secrets.tf
  │  │  └ variables.tf
  │  ├ staging
  │  │  ├ secrets.tf
  │  │  └ variables.tf
  │  └ production
  │     ├ secrets.tf
  │     └ variables.tf
  └ main.tpl
  

  优点

  • 适用于小型项目，项目中有少量资源
  • 容易传递参数到依赖资源

  缺点

  • 在项目的演变过程中，main.tpl 文件可能包含许多依赖资源

开发

要开始开发，您需要

• Docker
• Docker-compose

在连接到节点之前，您需要构建本地开发镜像并以分离模式启动它。从项目根目录运行以下命令

docker-compose -f docker-compose.dev.yml up -d

然后通过 exec 命令使用 bash 连接到 app 节点

docker-compose -f docker-compose.dev.yml exec app bash

现在，您就可以开始了！像平时一样在容器内部使用 cargo 工具命令。

许可协议

terraform-sage 项目采用 BSD 许可证发布。有关更多详细信息，请参阅 LICENSE 文件。