使用 Git 作为 Terraform 的状态管理后端

在进行基础设施即代码（Infrastructure as Code，IaC）实践时，Terraform 状态文件的管理一直是一个重要话题。本文将介绍如何使用 Git 作为 Terraform 的后端存储，这是一个特别适合个人项目和小型团队的解决方案。

背景

在使用 Terraform 管理多个项目的 GitHub Actions 密钥时，我遇到了状态文件存储的问题：

AWS S3 虽然是常用选择，但需要额外的成本
Cloudflare R2 等替代方案配置复杂，且存在诸多限制
对于开发者来说，Git 是最熟悉的版本控制工具

经过调研，我发现了 terraform-backend-git 这个优秀的工具，它完美地解决了上述问题。

实施步骤

1. 环境准备

首先需要安装 terraform-backend-git：

下载 terraform-backend-git 二进制文件
将其放置在系统 PATH 中（推荐放在 ~/.bin 目录）
在 ~/.zshrc 中添加：
```
export PATH=$PATH:$HOME/.bin
```

2. 项目结构

你可以参考我的模板仓库：https://github.com/zhaochunqi/terraform-git-backend-template

项目结构如下：

.
├── .envrc                 # 环境变量配置
├── justfile              # 任务自动化配置
├── README.md
├── sub/
│   └── terragrunt.hcl    # 子模块配置
└── terragrunt.hcl        # 主配置文件

3. 配置说明

项目使用了以下工具来优化工作流：

direnv：用于环境变量管理，详见我的文章：利用 direnv 管理项目环境变量，提高开发效率
just：用于自动化命令执行，特别是启用 terraform-backend-git，详见：探索 Just：让日常命令自动化的神器
terragrunt：用于管理 Terraform 配置和子模块，自动生成后端配置

4. 实施流程

创建用于存储 Terraform 状态的 Git 仓库（注意：需要包含 README 文件，避免空仓库）
配置项目中的 state 路径，确保与 GitHub 仓库路径匹配
使用 just 命令启用 terraform-backend-git 后端（需要配置 GitHub Token）
执行标准的 Terraform 工作流（init、plan、apply 等）

5. 解决 SSH 问题

在使用 just 命令启用 terraform-backend-git 后端时，可能会遇到 ssh-agent 相关的错误。这是因为该工具使用 SSH 来获取 state 仓库信息。解决方法如下：

确保你有用于访问 GitHub 的 SSH 密钥
将 SSH 密钥添加到 ssh-agent 中：
```
ssh-add ~/.ssh/your_github_ssh_key
```
验证 SSH 密钥已添加：
```
ssh-add -l
```
如果 ssh-agent 未运行，可以启动它：
```
eval "$(ssh-agent -s)"
```

完成这些步骤后，再次尝试使用 just 命令，应该就能成功启用 terraform-backend-git 后端了。

最佳实践

确保 GitHub Token 和 SSH 密钥安全存储，避免泄露
定期备份状态文件
在团队中统一使用相同的工具版本
遵循 Git 分支管理最佳实践

总结

使用 Git 作为 Terraform 后端存储是一个轻量级且高效的解决方案，特别适合：

个人项目开发
小型团队协作
需要版本控制的基础设施管理

通过结合 direnv、just 和 terragrunt 等工具，我们可以构建一个更加强大和易于管理的 IaC 工作流。同时，正确配置 SSH 访问对于顺利使用 terraform-backend-git 至关重要。

背景#

实施步骤#

1. 环境准备#

2. 项目结构#

3. 配置说明#

4. 实施流程#

5. 解决 SSH 问题#

最佳实践#

总结#

背景