importer-labs/gitlab/valet-custom-transformers-lab.md

Using Custom Transformers in a dry-run

In this lab we want to do a dry-run of the terraform-example project. Since we have already taken the dry-run lab we easily run the command and generate the GitHub workflow, but to our dismay Valet did not know how to transform the artifact report for Terraform and it shows as unsupported. After some research we determine that the action actions/upload-artifact would be an adequate substitute for it. This change will also require us to change the environment variable PLAN_JSON to point to a new value custom_plan.json. We need to make this change in many pipelines and an automated way to apply this would be ideal. Well, we are in luck we can use the --custom-transformers option of the dry-run command. This will allow us to change the behavior of Valet using a simple ruby file.

• Prerequisites
• Write Custom Transformers
• Run with Custom Transformers
• Next Lab

Prerequisites

1. Followed steps to set up your codespace environment.
2. Completed the configure lab
3. Completed the dry-run lab

Write Custom Transformers

• Let’s run the dry-run command to see what information we can get from the generated action yaml.

  gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-example
  

• Open the resulting GitHub Actions workflow by opening tmp/valet/custom-transformer.yml from the explorer

name: valet/custom-transformer
on:
  push:
  workflow_dispatch:
concurrency:
  group: "${{ github.ref }}"
  cancel-in-progress: true
jobs:
  plan:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    env:
      PLAN: plan.cache
      PLAN_JSON: plan.json
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 20
        lfs: true
    - run: terraform plan -out=$PLAN
    - run: terraform show --json $PLAN | convert_report > $PLAN_JSON
#     # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions

• We can see from the last line that artifacts.terraform was not transformed. In order for us to write a custom transformer for this we need to know the identifier. In general this will be the value between the back ticks, which in this case is artifacts.terraform. This is how our custom transformer will target the correct step.

• The custom transformers file can have any name, but it is recommend that you use a .rb extension so the codespaces editor knows it is a ruby file and can provide syntax highlighting.

• we have chosen the actions/upload-artifacts as our replacement so we should look at the docs to determine the correct final yaml

  - uses: actions/upload-artifact@v3
    with:
      path: VALUE_FROM_GITLAB
  

• Now we know the final yaml we can write the ruby file. In this file we will call the transform method. This is a special method that Valet exposes, that takes the identifier we determined earlier and returns a ruby Hash of the final YAML for the pipeline. The ruby Hash can be thought of as the JSON representation of the YAML we want. Valet will call that method when it encounters the identifier and pass in an item. The item is the values defined for that step in GitLab. In this case the path of the terraform report, if you were unsure you could use some basic ruby to print the item to the terminal by put the following line in the transform method puts "This is the item: #{item}".

  transform "artifacts.terraform" do |item|
    {
      uses: "actions/upload-artifact@v2",
      with: {
        path: item
      }
    }
  end
  

• The custom transformers file also lets you replace values of variables by using the env method. Let’s replace the value for PLAN_JSON by using the below line. The first value of the env method is the target variable name and the second is the new value to be used.

  env "PLAN_JSON", "custom_plan.json"
  

• create a new file in the root of the workspace called transformers.rb with the following contents

  env "PLAN_JSON", "custom_plan.json"
  
  transform "artifacts.terraform" do |item|
    {
      uses: "actions/upload-artifact@v2",
      with: {
        path: item
      }
    }
  end
  

Run Again with Customer Transformers

To run the dry-run with our custom transformer we will add the --custom-transformers option followed by the path of the ruby file

gh valet dry-run gitlab --output-dir tmp --namespace valet --project terraform-example --custom-transformers transformers.rb

The customer transformer worked and now we have the upload-artifact in the place of the unsupported result.

- #     # 'artifacts.terraform' was not transformed because there is no suitable equivalent in GitHub Actions
+ uses: actions/upload-artifact@v2
+ with:
+   path: "$PLAN_JSON"

Also we can see the PLAN_JSON env has been updated to custom_plan.json

 env:
   PLAN: plan.cache
-  PLAN_JSON: plan.json
+  PLAN_JSON: custom_plan.json

Now that we have this custom transformers file we can add additional transformand env methods as needed and reuse it while running other dry-run and migrate commands. The custom transformers will only affect the pipeline being transformed if they contain the matching identifiers. This means if you think a custom transformer should have altered the output, then the first thing to check is if the identifier is correct.

Next Lab

Audit a GitLab Namespace