1.6.9.1. YorBox

YorBox 是一个用于 Terraform 的开源命令行工具，旨在搭配 yor 辅助治理资源标签（tags）的统一管理。它采用 Go 语言编写，并利用 HashiCorp 提供的 HCL 库（如 hclwrite）对 Terraform 配置进行解析和改写。BridgeCrew Yor 本身可以自动为 IaC 模板添加标签，实现从代码到云端资源的追溯。然而，Yor 自动插入的标签在代码中是硬编码的，对使用者来说缺乏灵活性。YorBox 正是在这样的背景下诞生的，用于增强 Yor 标签治理的可控性和灵活性。

1.6.9.1.1. 核心功能与用途

YorBox 的核心功能是在运行 BridgeCrew Yor 自动打标签之后，对这些标签进行二次处理，使其变得可配置、可开关。

具体来说，YorBox 会扫描指定目录下所有 Terraform .tf 文件，检测出 Yor 自动生成的标签块，并将它们包装进一个带有条件判断的“盒子”（即 Terraform 的条件表达式）中。这个“盒子”由一个布尔型变量控制，用户可以通过设置变量开关来选择启用或禁用整组标签。经过 YorBox 处理后，原本硬编码的标签将被改写为类似 tags = (var.yor_toggle ? { ... } : {}) 的结构。其中 yor_toggle（名称可自定义）为开关变量，当其为 false 时，表达式返回空标签集，从而达到关闭自动标签的效果。借助这一机制，开发者可以在不同环境或场景下灵活控制是否应用由 Yor 注入的标签，确保标签的一致性管理的同时不失灵活性。

除了基本的标签开关功能，YorBox 还支持标签前缀及模板定制等高级用法。例如，BridgeCrew Yor 提供了自定义标签前缀的选项（--tag-prefix），在大规模项目中可用于区分不同来源的标签。当 Yor 使用了前缀（如 "avm_"）为标签命名时，YorBox 允许用户通过命令行参数指定该前缀（如 -tagsPrefix "avm_"），从而准确定位 Yor 生成的标签键。此外，YorBox 提供了盒子模板（Box Template）的配置能力，用户可以自定义包装标签的表达式格式。例如，可以定制模板在保留原有标签键的同时为其添加统一前缀或修改键名。这种定制通过 Go 模板语法实现，YorBox 在插入新标签块前会根据模板渲染出最终代码。总的来说，YorBox 的用途在于让自动标签过程可控可配：既能保持各模块标签的统一治理，又能根据需要启用/停用或调整标签，实现企业级规模下标签策略的灵活应用。

1.6.9.1.2. 为什么需要 YorBox？

在大规模 Terraform 模块治理中，引入 YorBox 主要是为了解决使用 BridgeCrew Yor 过程中遇到的痛点：

  • 无法按需禁用标签：BridgeCrew Yor 自动为资源添加追踪标签（如 git_commit, yor_trace 等），但在可复用的 Terraform 模块中，这些标签是直接写死在代码里的，模块使用者无法通过变量来控制是否应用这些标签。这带来了灵活性问题：并非所有部署环境或团队都需要这些附加标签，如果不能禁用，它们可能被视为冗余信息。
  • 标签命名固定：Yor 插入的标签键名通常固定（或统一加上某个前缀），在不同团队或项目中可能需要不同命名规范。例如，一个团队可能希望所有自动标签都有特定前缀，以避免与已有标签冲突。但在 Yor 原生功能下，这种调整需要在运行 Yor 时统一指定前缀，无法由模块使用者自主选择前缀或命名规则。
  • 版本控制噪音：每次运行 Yor 都会修改 Terraform 模块文件，添加/更新标签行。当团队在持续集成中频繁运行 Yor 时，仓库可能出现大量仅包含标签变更的提交。如果没有机制来控制标签注入的开启与否，某些场景下会引入不必要的版本控制噪音。

YorBox 正是针对上述问题提供了解决方案。通过为 Yor 自动标签加上条件开关，YorBox让模块的维护者能够预先将标签注入逻辑封装起来，赋予模块使用者选择权——例如通过设置 var.yor_toggle = false 来关闭标签注入。同时，YorBox 支持在包装标签时应用自定义模板和前缀策略，确保标签命名符合项目约定。简而言之，YorBox 提升了 Yor 在大型项目中的可治理性：既保留了自动标签带来的追溯便利，又避免了不必要的标签强制，减少了运维负担。

1.6.9.1.3. 安装与使用方法

作为一个独立的 CLI 工具，YorBox 的安装非常简便。由于其采用 Go 语言编写，用户可以直接使用 Go 自带的安装命令获取最新版本：

go install github.com/lonegunmanb/yorbox@latest

YorBox 的典型使用流程是和 BridgeCrew Yor 搭配进行的：

  1. 运行 Yor 自动打标签： 先使用 BridgeCrew Yor 对当前目录的 Terraform 代码进行标签注入，例如：
yor tag -d ./

这一步会按照 Yor 的规则为资源和模块添加追踪标签（如 Git 元数据和 yor_trace 等）。可以根据需要在此命令中加入如 --tag-prefix 等参数来控制标签格式。

  1. 运行 YorBox 包装标签： 在 Yor 执行完毕后，运行 YorBox 将刚才注入的标签转换为带开关的格式：
yorbox -dir . \
       -toggleName "yor_toggle" \
       -tagsPrefix ""

以上命令指定了目标目录（.表示当前目录），使用默认的开关变量名 yor_toggle，且假设 Yor 未使用额外前缀（如果 Yor 打标签时用了前缀则在此通过-tagsPrefix传入，例如 -tagsPrefix "avm_"）。YorBox 会扫描目录下的所有 .tf文件，在每个被 Yor 修改的资源或模块块中找到 Yor插入的标签，加入条件判断逻辑并写回文件。处理完成后，原本直接赋给 tags 的映射将变成一个包含三元表达式的结构，如：

   tags = /*<box>*/ var.yor_toggle ? /*</box>*/ {
     git_commit = "..." 
     git_file   = "..." 
     yor_trace  = "..."
     # ...省略若干 Yor 标签
   } /*<box>*/ : {} /*</box>*/

现在，变量 yor_toggle 的值决定了这组标签是否生效：为 true 时应用标签，为 false 时为空。

YorBox 提供了一些可选参数来适应不同场景：

  • 使用 -toggleName <名称> 可自定义开关变量名称（默认为 yor_toggle），以避免与项目中其它变量命名冲突。
  • 使用 -tagsPrefix <前缀> 来指定 Yor 插入标签时使用的键名前缀（如果有），确保 YorBox 能正确识别出哪些标签需要被包装。例如，若 Yor 插入了 my_prefix_git_commit 这样的标签键，则运行 YorBox 时应加选项 -tagsPrefix "my_prefix_"，这样工具会查找以该前缀开头的 git_commit 等标签键进行处理。
  • 使用 -boxTemplate '<模板字符串>' 可以覆盖默认的包装模板。默认模板相当于将标签简单地包裹在 (var.toggle ? { ... } : {}) 中，有经验的用户可以通过自定义模板实现更复杂的逻辑（如在示例中使用 for 表达式批量替换键名前缀）。一般情况下默认行为已能满足需求，除非有特殊定制需求，否则可不使用此高级参数。

需要注意，YorBox 在往文件中插入条件标签时，会使用特殊的标记注释（如 /*<box>*/ 和 /*</box>*/）包围生成的代码片段。这些标记不会影响 Terraform 配置的执行，但用于提示 YorBox 下次运行时识别已有的“盒子”区域，从而避免重复包装或方便重新应用新的模板格式。如果需要更新已存在的标签盒子，YorBox 会先移除旧的标记和代码，再插入新的结构。因此，重复运行 YorBox 是幂等的，可以安全地在持续集成环境中反复执行。

当模块使用者需要启用这些标签时，只需在 Terraform 调用模块时将 yor_toggle 变量设为 true 即可；反之默认为 false 时模块将不包含任何追踪标签。例如，在 Terraform 配置中引用该模块时可以这样设置开关和前缀：

module "example" {
  source               = "azure/xxx/azurerm"
  # ...其他参数...
  yor_toggle           = true             # 启用自动追踪标签
}

1.6.9.1.4. boxTemplate 的灵活运用

盒子模板（BoxTemplate）是一个用于生成“盒子”表达式的 Go 模板。盒子模板支持用户传入变量。例如，默认模板如下：

/*<box>*/(var.{{ .toggleName }} ? /*</box>*/ { yor_trace = 123 } /*<box>*/ : {})/*</box>*/

通过如下命令：

$ yorbox -dir <目录> -toggleName "my_toggle"

生成的代码为：

tags = (/*<box>*/(var.my_toggle ? /*</box>*/{
  git_commit           = "898d5beaec7ffdef6df0d7abecff407362e2a74e"
  git_file             = "terraform/azure/aks.tf"
  git_last_modified_at = "2020-06-17 12:59:55"
  git_last_modified_by = "nimrodkor@gmail.com"
  git_modifiers        = "nimrodkor"
  git_org              = "bridgecrewio"
  git_repo             = "terragoat"
  yor_trace            = "6103d111-864e-42e5-899c-1864de281fd1"
}/*<box>*/ : {})/*</box>*/ )

可用变量有：

  • dirPath：对应 -dir
  • toggleName：对应 -toggleName
  • tagsPrefix：对应 -tagsPrefix

1.6.9.1.4.1. 如何用 BoxTemplate 为标签键统一添加前缀

以下是通过 -boxTemplate 参数批量为所有标签键添加前缀的实际操作流程说明：

1. 先运行 Yor 注入标签

假设你的 Terraform 资源已经被 BridgeCrew Yor 自动加上了一组标签，比如：

resource "azurerm_resource_group" "example" {
  name     = "example-rg"
  location = "East US"

  tags = {
    git_commit = "xxxxxx"
    yor_trace  = "xxxxxx"
  }
}

2. 执行 YorBox，并自定义盒子模板

你希望所有由 Yor 注入的标签都加上统一前缀，比如 my_prefix_，这时你可以这样运行：

yorbox -dir . \
  -boxTemplate '/*<box>*/(var.{{ .toggleName }} ? { for k,v in /*</box>*/ { yor_trace = 123 } /*<box>*/ : "my_prefix_${k}"=>v } : {})/*</box>*/'

这里 -boxTemplate 用于指定盒子模板。模板的关键逻辑是：

  • 在三元表达式的 { for k,v in ... : "my_prefix_${k}"=>v } 结构内，将原本的标签键用 "my_prefix_${k}" 替代，实现所有标签键自动加上统一前缀。

3. 生成后的标签块示例

处理后你会看到标签块变成：

tags = (/*<box>*/(var.yor_toggle ? { for k,v in /*</box>*/{
  git_commit = "xxxxxx"
  yor_trace  = "xxxxxx"
}/*<box>*/ : "my_prefix_${k}"=>v } : {})/*</box>*/)

这表示：

  • 当 yor_toggle 为 true 时，所有 Yor 标签将自动加上 my_prefix_ 前缀并注入到资源中。
  • 当 yor_toggle 为 false 时，不添加任何标签。

1.6.9.1.5. 小结

综上所述，YorBox 作为 BridgeCrew Yor 的有力补充，解决了自动标签在模块化场景下的诸多痛点。在实际项目中应用 YorBox，可以令 Terraform 模块的标签治理更加规范、灵活和可控——既满足了云资源追踪审计的要求，又给予使用者足够的自主权来决定标签的取舍，从而实现大规模基础设施即代码项目中标签的一致性治理。

results matching ""

    No results matching ""