1.6.9.1. YorBox

YorBox is an open-source command-line tool for Terraform, designed to work with yor to facilitate the unified governance of resource tags. It is written in Go and leverages HashiCorp's HCL libraries (such as hclwrite) to parse and rewrite Terraform configurations. BridgeCrew Yor itself can automatically add tags to IaC templates, enabling traceability from code to cloud resources. However, the tags automatically inserted by Yor are hardcoded in the code, lacking flexibility for users. YorBox was created against this backdrop to enhance the controllability and flexibility of Yor tag governance.

1.6.9.1.1. Core Features and Use Cases

The core function of YorBox is to perform secondary processing on tags after BridgeCrew Yor has automatically added them, making these tags configurable and toggleable.

Specifically, YorBox scans all Terraform .tf files in a specified directory, detects the tag blocks automatically generated by Yor, and wraps them into a "box" with conditional logic (i.e., a Terraform conditional expression). This "box" is controlled by a boolean variable, allowing users to enable or disable the entire set of tags by toggling the variable. After processing by YorBox, the originally hardcoded tags are rewritten into a structure similar to tags = (var.yor_toggle ? { ... } : {}). Here, yor_toggle (the name is customizable) is the switch variable; when it is false, the expression returns an empty set of tags, effectively turning off automatic tagging. With this mechanism, developers can flexibly control whether to apply the tags injected by Yor in different environments or scenarios, ensuring consistent tag management without losing flexibility.

In addition to the basic tag toggling function, YorBox also supports advanced usages such as tag prefixes and template customization. For example, BridgeCrew Yor provides an option to customize tag prefixes (--tag-prefix), which enables distinguishing tags from different sources in large-scale projects. When Yor uses a prefix (such as "avm_") to name tags, YorBox allows users to specify that prefix via command-line arguments (such as -tagsPrefix "avm_"), thereby accurately locating the tag keys generated by Yor. Furthermore, YorBox offers Box Template configuration capabilities, allowing users to customize the format of the expression wrapping the tags. For instance, you can customize a template to add a unified prefix to tag keys or modify key names while retaining the original ones. This customization is implemented using Go template syntax, and YorBox renders the final code based on the template before inserting the new tag block. In summary, the purpose of YorBox is to make the automatic tagging process controllable and configurable: it maintains unified governance of tags across modules while allowing tags to be enabled/disabled or adjusted as needed, achieving flexible application of tag strategies at an enterprise scale.

1.6.9.1.2. Why is YorBox Needed?

In the governance of large-scale Terraform modules, introducing YorBox mainly addresses the pain points encountered when using BridgeCrew Yor:

  • Inability to disable tags on demand: BridgeCrew Yor automatically adds tracking tags (such as git_commit, yor_trace, etc.) to resources, but in reusable Terraform modules, these tags are hardcoded directly into the code, and module users cannot control whether to apply them via variables. This creates a flexibility issue: not all deployment environments or teams need these additional tags, and if they cannot be disabled, they might be considered redundant information.
  • Fixed tag naming: The tag keys inserted by Yor are usually fixed (or uniformly prefixed). Different teams or projects may require different naming conventions. For example, a team might want all automatic tags to have a specific prefix to avoid conflicts with existing tags. However, with Yor's native functionality, such adjustments need to be uniformly specified when running Yor, and cannot be chosen independently by module users.
  • Version control noise: Every time Yor runs, it modifies Terraform module files to add/update tag lines. When teams run Yor frequently in continuous integration pipelines, the repository may accumulate a large number of commits containing only tag changes. Without a mechanism to control whether tag injection is enabled, unnecessary version control noise can be introduced in some scenarios.

YorBox provides solutions to these problems. By adding a conditional switch to Yor's automatic tags, YorBox allows module maintainers to encapsulate the tag injection logic, giving module users the right to choose—for example, by setting var.yor_toggle = false to turn off tag injection. At the same time, YorBox supports applying custom templates and prefix strategies when wrapping tags, ensuring that tag naming conforms to project conventions. In short, YorBox improves the governability of Yor in large projects: it retains the traceability convenience brought by automatic tagging while avoiding unnecessary mandatory tags and reducing operational burdens.

1.6.9.1.3. Installation and Usage

As a standalone CLI tool, installing YorBox is very simple. Since it is written in Go, users can directly use the Go installation command to get the latest version:

go install github.com/lonegunmanb/yorbox@latest

The typical usage workflow for YorBox involves pairing it with BridgeCrew Yor:

  1. Run Yor for automatic tagging: First, use BridgeCrew Yor to inject tags into the Terraform code in the current directory, for example:
yor tag -d ./

This step will add tracking tags (such as Git metadata and yor_trace, etc.) to resources and modules according to Yor's rules. You can add parameters like --tag-prefix to this command as needed to control the tag format.

  1. Run YorBox to wrap tags: After Yor finishes execution, run YorBox to convert the injected tags into a format with a switch:
yorbox -dir . \
       -toggleName "yor_toggle" \
       -tagsPrefix ""

The above command specifies the target directory (. represents the current directory), uses the default switch variable name yor_toggle, and assumes Yor did not use an extra prefix (if Yor used a prefix when tagging, pass it here via -tagsPrefix, e.g., -tagsPrefix "avm_"). YorBox will scan all .tf files in the directory, find the tags inserted by Yor in each modified resource or module block, add conditional logic, and write them back to the file. After processing, the map originally assigned to tags will become a structure containing a ternary expression, such as:

   tags = /*<box>*/ var.yor_toggle ? /*</box>*/ {
     git_commit = "..." 
     git_file   = "..." 
     yor_trace  = "..."
     # ...omitted Yor tags
   } /*<box>*/ : {} /*</box>*/

Now, the value of the variable yor_toggle determines whether this set of tags takes effect: when true, the tags are applied; when false, it is empty.

YorBox provides some optional parameters to adapt to different scenarios:

  • Use -toggleName <name> to customize the switch variable name (default is yor_toggle) to avoid naming conflicts with other variables in the project.
  • Use -tagsPrefix <prefix> to specify the key name prefix used when Yor inserts tags (if any), ensuring that YorBox can correctly identify which tags need to be wrapped. For example, if Yor inserted tag keys like my_prefix_git_commit, run YorBox with the option -tagsPrefix "my_prefix_", so the tool will look for tag keys starting with that prefix like git_commit for processing.
  • Use -boxTemplate '<template_string>' to override the default wrapping template. The default template simply wraps the tags in (var.toggle ? { ... } : {}). Experienced users can implement more complex logic through custom templates (such as using for expressions to batch replace key name prefixes in an example). Generally, the default behavior meets the needs, and this advanced parameter is not used unless there are special customization requirements.

It should be noted that when YorBox inserts conditional tags into files, it uses special marker comments (such as /*<box>*/ and /*</box>*/) to surround the generated code snippets. These markers do not affect the execution of the Terraform configuration, but are used to prompt YorBox to identify existing "box" areas when run next time, thereby avoiding repeated wrapping or facilitating the re-application of new template formats. If existing tag boxes need to be updated, YorBox will first remove old markers and code, and then insert the new structure. Therefore, repeated execution of YorBox is idempotent and can be safely executed repeatedly in continuous integration environments.

When module users need to enable these tags, they only need to set the yor_toggle variable to true when calling the module in Terraform; conversely, when it defaults to false, the module will not contain any tracking tags. For example, when referencing the module in a Terraform configuration, you can set the switch and prefix like this:

module "example" {
  source               = "azure/xxx/azurerm"
  # ...other parameters...
  yor_toggle           = true             # Enable automatic tracking tags
}

1.6.9.1.4. Flexible Use of boxTemplate

Box Template (BoxTemplate) is a Go template used to generate the "box" expression. The box template supports user-passed variables. For example, the default template is as follows:

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

By running the command:

$ yorbox -dir <directory> -toggleName "my_toggle"

The generated code is:

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>*/ )

Available variables are:

  • dirPath: corresponds to -dir
  • toggleName: corresponds to -toggleName
  • tagsPrefix: corresponds to -tagsPrefix

1.6.9.1.4.1. How to use BoxTemplate to add a unified prefix to tag keys

The following is an operational guide on how to batch add prefixes to all tag keys via the -boxTemplate parameter:

1. First, run Yor to inject tags

Assume your Terraform resources have been automatically tagged by BridgeCrew Yor, for example:

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

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

2. Execute YorBox and customize the box template

You want all tags injected by Yor to have a unified prefix, such as my_prefix_. You can run:

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

Here, -boxTemplate is used to specify the box template. The key logic of the template is:

  • Inside the ternary expression { for k,v in ... : "my_prefix_${k}"=>v } structure, replace the original tag keys with "my_prefix_${k}", achieving the automatic addition of unified prefixes to all tag keys.

3. Example of the generated tag block

After processing, you will see the tag block become:

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

This means:

  • When yor_toggle is true, all Yor tags will automatically be prefixed with my_prefix_ and injected into the resource.
  • When yor_toggle is false, no tags will be added.

1.6.9.1.5. Summary

In summary, as a powerful supplement to BridgeCrew Yor, YorBox solves many pain points of automatic tagging in modular scenarios. Applying YorBox in actual projects can make tag governance of Terraform modules more standardized, flexible, and controllable—satisfying both cloud resource tracking and auditing requirements, and giving users enough autonomy to decide on tag adoption, thereby achieving consistent governance of tags in large-scale Infrastructure as Code projects.

results matching ""

    No results matching ""