Atlantis

https://github.com/runatlantis/atlantis

一个独立的服务器来负责运行 terrform plan 和 apply

流程

修改代码, 提交到 git dev 分支, 并创建分支合并 MR
git webhook 触发, 将 MR 事件发送给 Atlantis
Atlantis 拉取代码, 并执行 plan
将 plan 的结果以评论的方式发布到 MR 中
团队 Review 后, 有权限的人在 MR 中评论 atlantis apply
Atlantis 执行 terraform apply, 并将结果评论到 MR 中

优势

自动管理 Lock, 同一目录并发操作自动排队 / 拒绝
凭证仅存储在 Atlantis 服务器上
所有 plan 和 apply 结果都作为评论保留在 MR 中
可通过 GitLab 的 Approval 规则和权限控制谁能执行 apply
环境一致性

在 PR 上评论：
atlantis plan
atlantis apply

实践

可以在 ci 流程中进行代码静态检查等操作
实际 plan apply 再由 atlantis 进行操作

多副本部署：Atlantis 支持多副本运行，但需要配置共享的锁后端（如 Redis 或数据库），默认使用内存锁

在 GitLab 中配置 Atlantis

创建 GitLab Access Token

推荐使用 Project Access Token 或 Group Access Token

所需权限(Scopes):
api (完整 API 访问, 用于读写 MR 评论, 读取代码)
或者精细控制: read_repository, write_registry, api (GitLab 目前对 MR 评论写入通常需要 api scope)
角色: 至少需要 Maintainer 角色(如果需要合并 MR)或 Developer(仅评论和 plan)

部署 Atlantis 服务

Atlantis 服务器必须有公网可达的 URL, 因为要 webhook 回调

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


docker run -d \
   --name atlantis \
   -p 4141:4141 \
   -e ATLANTIS_GITLAB_HOSTNAME=gitlab.com \             # 或你的自建 GitLab 域名
   -e ATLANTIS_GITLAB_TOKEN=<your-gitlab-token> \        # 步骤 1 创建的 Token
   -e ATLANTIS_GITLAB_USER=atlantis-bot \                # Token 对应的用户名
   -e ATLANTIS_GITLAB_WEBHOOK_SECRET=<your-secret> \     # Webhook 验证密钥
   -e ATLANTIS_REPO_ALLOWLIST=gitlab.com/mygroup/* \     # 允许 Atlantis 运行的仓库白名单
   -e ATLANTIS_PORT=4141 \
   -v /path/to/atlantis/data:/home/atlantis \            # 持久化数据(Lock, cloned repos)
   ghcr.io/runatlantis/atlantis:latest server

在 Atlantis 服务器上配置 Terraform 需要的云厂商凭证

配置 GitLab Webhook

进入 GitLab 项目 → Settings → Webhooks

URL: https://your-atlantis-domain.com/events

Secret token: 与 Atlantis 的 ATLANTIS_GITLAB_WEBHOOK_SECRET 保持一致

Trigger（触发事件）
必须勾选：
✅ Merge request events （MR 创建、更新、关闭）
✅ Comments （Note events，用于接收 atlantis apply 等指令）

MR核心工作流

1
2
3
4
5
6


# 开发者本地操作
git checkout -b feature/add-s3-bucket
# 修改 terraform/main.tf ...
git add .
git commit -m"feat: add S3 bucket for logs"
git push origin feature/add-s3-bucket

然后在 GitLab 上创建 Merge Request（源分支 feature/add-s3-bucket → 目标分支 main）

阶段 2：Atlantis 自动 Plan

MR 创建后几秒内，Atlantis 会：
检测到 MR 中修改了 terraform/ 目录下的 .tf 文件
自动在该目录下执行 terraform init 和 terraform plan
将 Plan 结果以评论形式发布到 MR 中：
同时，Atlantis 会锁定该目录（Lock），防止其他 MR 同时修改同一目录导致状态冲突

Code Review
如果代码需要修改

1
2
3


# 开发者修改代码后再次 push
 git commit -am"fix: add encryption to s3 bucket"
 git push origin feature/add-s3-bucket

Atlantis 检测到新的 push，会自动重新执行 Plan 并更新 MR 中的评论

Review 通过后，有权限的用户（通常是 Maintainer 或指定角色）在 MR 评论区输入：

1

atlantis apply -d terraform

Atlantis 收到指令后：

验证评论者是否有权限执行 apply
执行 terraform apply -auto-approve
将结果评论到 MR 中

合并 MR 与解锁

Apply 成功后，可以手动合并 MR（或配置自动合并）
MR 合并/关闭后，Atlantis 会自动解锁该目录，允许其他 MR 继续操作

常用评论命令速查表

命令必须以 atlantis 开头，且单独成行; 支持在一条评论中写多行命令

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


命令            说明
atlantis plan               对所有变更目录重新执行 plan
atlantis plan -d <dir>      对指定目录执行 plan
atlantis plan -w <workspace>    对指定 workspace 执行 plan
atlantis apply              对所有已 plan 且未锁定的目录执行 apply
atlantis apply -d <dir>     对指定目录执行 apply
atlantis apply -p <project> 对 atlantis.yaml 中定义的特定项目执行 apply
atlantis unlock             手动解锁当前 MR 锁定的目录
atlantis version            显示 Atlantis 和 Terraform 版本
atlantis help               显示帮助信息

atlantis.yaml

放在仓库根目录的配置文件，用于精细化控制 Atlantis 的行为
对于多环境、多目录、多 Workspace 的复杂项目至关重要

示例：多目录多环境

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


version: 3

# 项目列表，每个项目对应一个 Terraform Root Module
projects:

    # name 项目唯一标识，用于在评论中通过 -p <name> 指定
   - name: dev-networking

    # Terraform 代码所在目录（相对于仓库根目录）
     dir: environments/dev/networking
     workspace: default                 # Terraform Workspace 名称

     # 定义哪些文件变更会触发自动 Plan
     autoplan:
       when_modified: ["*.tf","*.tfvars","../modules/networking/**/*"]

       # 是否启用自动 Plan（设为 false 则需手动评论 atlantis plan）
       enabled: true

     # 安全控制，定义 Apply 前必须满足的条件
     # approved: MR 必须获得 GitLab Approvals（至少一个 Approve）。这直接集成 GitLab 的审批功能
     # mergeable: MR 必须处于"可合并"状态（即：无冲突、Pipeline 通过、满足 Approval 规则等）
     # unlocked：目录未被其他 MR 锁定
     apply_requirements: ["approved"]

   - name: prod-networking
     dir: environments/prod/networking
     workspace: default
     autoplan:
       when_modified: ["*.tf","*.tfvars","../modules/networking/**/*"]
       enabled: true
     apply_requirements: ["approved","mergeable"]

   - name: dev-app
     dir: environments/dev/app
     workspace: default
     autoplan:
       when_modified: ["*.tf","*.tfvars"]
       enabled: true

自定义 Workflow

可以在 atlantis.yaml 中定义自定义的 plan/apply 步骤，例如集成 terragrunt 或 checkov

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


version: 3
workflows:
   terragrunt:
     plan:
       steps:
         - env:
             name: TERRAGRUNT_IAM_ROLE
             value: "arn:aws:iam::123456:role/terraform"
         - run: terragrunt plan -out=$PLANFILE
     apply:
       steps:
         - run: terragrunt apply -auto-approve $PLANFILE

projects:
   - name: my-project
     dir: live/production
     workflow: terragrunt