Terraform Execution Flow

When running a job inside the executor component the following logic is used:

• A folder to execute the job will be created using the organization id and workspace id:

  • /home/cnb/.terraform-spring-boot/executor/{{ORGANIZATION_ID}}//{{WORKSPACE_ID}}

• The executor component will initially clone the workspace to the following folder:

  • /home/cnb/.terraform-spring-boot/executor/{{ORGANIZATION_ID}}//{{WORKSPACE_ID}}/.originRepository

  • This is a shallow clone (--depth 1) of the branch tip when no specific commit is requested, which is faster on large repositories. A job that must check out a specific historical commit (for example an apply running against the commit recorded at plan time) automatically falls back to fetching that commit directly, or a full clone if the server doesn't support fetching by SHA.

• All the files inside ".originalRepository" are moved to {{ORGANIZATION_ID}}//{{WORKSPACE_ID}} folder from previous step.

• Te executor component will create the extension folders where you can store BASH or GROOVY extensions:

  • /home/cnb/.terraform-spring-boot/executor/{{ORGANIZATION_ID}}/{{WORKSPACE_ID}}/.terrakube/toolsRepository

    • By default it will clone the repository "https://github.com/AzBuilder/terrakube-extensions", this can be change by using TerrakubeToolsRepository and TerrakubeToolsBranch environment variables.

  • The executor component will scan the extension folder and will add all the "sh" files to the linux path when using BASH commands.

  • The executor component will scan the extension folder and will add all the ".groovy" files as Groovy dependencies dynamical when using GROOVY commands.

    • When using GROOVY extension to download an external tools, the extension can use the following folder /home/cnb/.terraform-spring-boot/executor/{{ORGANIZATION_ID}}/{{WORKSPACE_ID}}/.terrakube/tools all the folder inside the "tools" folder are also included in the linux execution PATH

  • By default the executor component will also include all the "sh" from the imported workspace files

• Once the executor component has all the necesarry information it will execute the selected template flow for the job.

• When the job execution is completed the current {{ORGANIZATION_ID}}/{{WORKSPACE_ID}} is deleted.

An example of how to import external tools can be found in the Terratag Groovy extension

https://github.com/AzBuilder/terrakube-extensions/tree/main/groovy/TerraTag

This extension download the terratag binary and expose the binary to be used inside the linux PATH when using BASH commands.

A command's before/beforeInit/after flags control when it runs relative to terraform init and the step's main command (plan/apply/destroy):

Flag	Runs
beforeInit	Before terraform init. If a beforeInit script fails, init is skipped entirely.
before	After init, before the main command. Ignored if beforeInit is also set.
after	After the main command succeeds.

A separate onFailure list (a sibling of commands, not a flag on a command) runs only if the step's main command fails — use it for cleanup or failure notifications instead of after, which only runs on success.

When using the following template:

flow:
  - type: "terraformPlan"
    name: "Plan"
    step: 100
    commands:
      - runtime: "GROOVY"
        priority: 100
        before: true
        script: |
          import TerraTag
          new TerraTag().loadTool(
            "$workingDirectory",
            "$bashToolsDirectory",
            "0.1.30")
          "Terratag download completed"
      - runtime: "BASH"
        priority: 200
        before: true
        script: |
          helloWorld.sh
    onFailure:
      - runtime: "BASH"
        priority: 100
        script: |
          notifyFailure.sh

The following directory structure will be generating when using a workspace with the workspace with "https://github.com/AzBuilder/terrakube-docker-compose"

  | - .originRepository
  |  | - .git
  |  |  | - refs
  |  |  |  | - heads
  |  |  |  | - tags
  |  |  | - logs
  |  |  |  | - refs
  |  |  |  |  | - heads
  |  |  | - objects
  |  |  |  | - info
  |  |  |  | - pack
  |  |  | - branches
  |  |  | - hooks
  |  | - getting-started
  |  | - local
  | - .git
  |  | - refs
  |  |  | - heads
  |  |  | - tags
  |  | - logs
  |  |  | - refs
  |  |  |  | - heads
  |  | - objects
  |  |  | - info
  |  |  | - pack
  |  | - branches
  |  | - hooks
  | - getting-started
  | - local
  | - .terraform
  |  | - providers
  |  |  | - registry.terraform.io
  |  |  |  | - hashicorp
  |  |  |  |  | - null
  |  |  |  |  |  | - 3.2.1
  |  |  |  |  |  |  | - linux_amd64
  |  |  |  |  | - time
  |  |  |  |  |  | - 0.9.1
  |  |  |  |  |  |  | - linux_amd64
  | - .terrakube
  |  | - tools
  |  |  | - terratag
  |  | - toolsRepository
  |  |  | - .git
  |  |  |  | - refs
  |  |  |  |  | - heads
  |  |  |  |  | - tags
  |  |  |  |  | - remotes
  |  |  |  |  |  | - origin
  |  |  |  | - logs
  |  |  |  |  | - refs
  |  |  |  |  |  | - heads
  |  |  |  | - objects
  |  |  |  |  | - info
  |  |  |  |  | - pack
  |  |  |  | - branches
  |  |  |  | - hooks
  |  |  | - bash
  |  |  |  | - helloWorld
  |  |  |  | - terratag
  |  |  | - groovy
  |  |  |  | - Context
  |  |  |  | - Infracost
  |  |  |  | - Opa
  |  |  |  | - Sendgrid
  |  |  |  | - SlackApp
  |  |  |  | - Snyk
  |  |  |  | - TerraTag
  |  |  |  | - Terrascan
  |  |  | - policy
  |  |  | - templates
  |  |  |  | - terratag