Azure Pipelines中Terragrunt S3后端目录结构异常排查

项目目录结构 #

├── dev
│   ├── modules
│   │   ├── _backend.tf
│   │   ├── acm
│   │   ├── eks
│   │   ├── eks-resources
│   │   │   ├── efs
│   │   │   ├── irsa
│   │   │   ├── node-roles
│   │   │   ├── node-roles-win
│   │   │   ├── nodegroups
│   │   │   ├── routes
│   │   │   ├── storageclases
│   │   │   ├── vpc-endpoints
│   │   │   ├── vpc-endpoints-sg
│   │   ├── eks-vpc
│   │   ├── main_provider.tf
│   │   ├── route53
│   │   └── terragrunt.hcl
│   └── terragrunt.hcl
├── dev2
└── dev3

dev2和dev3具有完全相同的目录结构。

后端配置（Terragrunt） #

remote_state {
  backend = "s3"
  generate = {
    path      = "_backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket  = "tfstate-${local.aws_region.locals.aws_region}-${local.account.locals.aws_account_name}-${local.account.locals.aws_account_id}"
    key     = "${path_relative_to_include()}/${local.env_common.locals.env_name}/terraform.tfstate"
  }
}

问题现象 #

• 本地在terragrunt/development/us-east-1/environments/dev目录下运行命令：

  terragrunt run-all plan/apply --terragrunt-include-external-dependencies --terragrunt-non-interactive
  

  S3存储桶中会正常生成acm、eks等目录，每个目录下包含dev、dev2、dev3子目录，内部存放对应terraform.tfstate文件。
• 在Azure Pipelines中运行相同命令时，S3中会生成一个额外的env:目录，所有原有的acm、eks等目录都被包含在env:目录下，导致生成全新的状态文件，无法复用本地已有的状态。

已确认流水线中的运行目录与本地一致。

可能原因 #

1. 环境变量干扰：Azure Pipelines默认会设置一些环境变量，若存在TG_ENV或其他Terragrunt相关的环境变量，可能会覆盖local.env_common.locals.env_name的取值，或者改变path_relative_to_include()的计算基准，从而生成带env:前缀的路径。
2. 工作目录的隐性差异：虽然表面上运行目录一致，但Linux系统大小写敏感，若流水线中checkout的代码目录大小写与本地不一致，或者存在符号链接、挂载目录等情况，会导致Terragrunt解析相对路径时出现偏差。
3. Terragrunt版本不一致：本地与流水线使用的Terragrunt版本不同，path_relative_to_include()函数的行为在不同版本中可能存在差异，比如路径分隔符处理、环境变量优先级等。
4. include文件的路径解析问题：如果Terragrunt的include配置中使用了相对路径，流水线环境中可能因为目录层级的隐性差异，导致path_relative_to_include()的基准目录发生变化，生成异常路径。

调试方法 #

• 打印关键变量值：在流水线中添加步骤，运行terragrunt run-all plan --terragrunt-debug，查看输出中path_relative_to_include()、local.env_common.locals.env_name的实际取值，与本地运行的debug输出做对比，定位变量取值异常的部分。
• 确认当前工作目录细节：在流水线中执行pwd（Linux/macOS）或cd（Windows）命令，输出完整路径，同时检查目录的大小写（Linux环境）、是否存在符号链接等，确保和本地完全一致。
• 排查环境变量：在流水线中执行printenv（Linux/macOS）或set（Windows）命令，列出所有环境变量，重点检查TG_*开头的变量，比如TG_ENV、TG_WORKING_DIR，这些变量会直接影响Terragrunt的行为。
• 统一Terragrunt版本：在流水线中指定与本地完全一致的Terragrunt版本，比如使用固定版本的安装脚本，避免版本差异导致的函数行为变化。
• 手动验证路径计算：在流水线中，直接运行terragrunt config path_relative_to_include（需对应版本支持），获取该函数的实际返回值，对比本地的计算结果，确认路径基准是否一致。
• 临时修改后端配置调试：暂时修改S3的key配置，添加更多调试信息，比如：

  key = "DEBUG-${path_relative_to_include()}-${local.env_common.locals.env_name}/terraform.tfstate"
  

  运行后查看S3中生成的路径，明确是哪一部分变量导致了env:前缀的出现。

内容的提问来源于stack exchange，提问作者Shayki Abramczyk