1 of 7

Templates

Templates allows you to customize the job workflow inside each workspace. You can define multiple templates inside each organization. Templates are written in yaml and you can specify each step to be executed once you use this template in the workspace. Lets see an example for a basic template:

Example 1:

flow:
  - name: "Plan"
    type: "terraformPlan"
    step: 100
  - name: "Apply"
    type: "terraformApply"
    step: 200

Example 2:

flow:
- type: "terraformPlanDestroy"
  name: "Terraform Plan Destroy from Terraform CLI"
  step: 100
- type: "approval"
  name: "Approve Plan from Terraform CLI"
  step: 150
  team: "TERRAFORM_CLI"
- type: "terraformApply"
  name: "Terraform Apply from Terraform CLI"
  step: 200

Example 3:

flow:
  - type: "terraformDestroy"
    step: 100
  - type: "disableWorkspace"
    step: 200

If you notice inside the flow section you can define any step required, for this case only 2 steps are defined. Using the type property you can specify the kind of step to be performed, in the above case we are using some default types like terraformPlan and terraformApply. However the power of terrakube is that you can extend your workflow to execute additional tasks using bash or groovy code. Lets see a more advanced template:

flow:
  - name: "Plan"
    type: "terraformPlan"
    step: 100
    commands:
      - runtime: "GROOVY"
        priority: 100
        before: true
        script: |
          @Grapes([
            @Grab('commons-io:commons-io:2.8.0'),
            @Grab('org.apache.commons:commons-compress:1.21'),
          ])

          import org.apache.commons.io.FileUtils
          
          class TerraTagDownloader {
            def downloadTerraTag(workingDirectory, version, os, arch) {
              String terraTagFile = "terratag_${version}_${os}_${arch}.tar.gz"
              String terraTagURL = "https://github.com/env0/terratag/releases/download/v${version}/${terraTagFile}"
              println "Downloading $terraTagURL"
              FileUtils.copyURLToFile(new URL(terraTagURL), new File("${workingDirectory}/${terraTagFile}"))
            }
          } 
          new TerraTagDownloader().downloadTerraTag("$workingDirectory", "0.1.29", "darwin", "amd64")
          "TerraTag Download Compledted..."
      - runtime: "BASH"
        priority: 200
        before: true
        script: |
          cd $workingDirectory;
          tar -xvf terratag_0.1.29_darwin_amd64.tar.gz;
          chmod +x terratag;
          ./terratag -tags="{\"environment_id\": \"development\"}"
  - name: "Apply"
    type: "terraformApply"
    step: 300
  - name: "Destroy"
    type: "terraformDestroy"
    step: 400

The previous example is using Terratag to add the environment_id to all the resources in the workspace. To acomplish that, the template defines some additional commands during the Terraform Plan, in this case a groovy class is utilized to download the Terratag binary, and a bash script is used to execute the terratag cli to append the required tags.

Using templates you can define all the business logic you need to execute in your workspace, basically you can integrate terrakube with any external tool. For example you can use Infracost to calculate the cost of the resources to be created in your workspace or verify some policies using Open Policy Agent.

Terrakube extensions can be stored inside a GIT repository that you can configure when staring the platform. This is an example repository that you can fork or customiza to create your custom extensions https://github.com/AzBuilder/terrakube-extensions

There are some tools that are very common, and you don't want repeat the same code everytime or maybe other engineer already created the code and the logic to integrate with a specific tool. For these cases, inside the template is possible to reuse some logic using Terrakube extensions. Basically if someone else developed an integration with an external third party service, you don't need to implement it again, you can use the extension. Let's see how the template looks like using the Terratag extension:

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

If you notice the above script is more compact as is reusing some logic. If you want to simplify and reuse some templates in your organization, please check Import Templates.

Using Templates you can even customize the UI for each job, see UI templates for more details.

To see the complete list for terrakube extensions see the github repo. This repo is always growing so its possible the tool you need is already there. In this repo you can also see more templates examples for things like approvals, variable injection and so on.

Persistent Context

If you need to store information generated on the steps defined in your template, you can use persistent context.

Creating a Template

Manage VCS Templates permission is required to perform this action, please check Team Management for more info

Once you are in the desired organization, click the Settings button, then in the left menu select the Templates option and click the Add Template button

You will see a list of some predefined templates than you can utilize as a quick start or if you prefer you can click the Blank Template to start from scratch

In the next screen you can define your template and when you are ready click the Continue button.

Finally, you can assign a name and description to your template and click the Create Template button.

Now you template is ready and you can start using it in any workspace within your organization.

By default Terrakube don't create any template, so you have to define the templates in your organization based on your requirements.

Editing a Template

Click the Edit button next to the Template you would like to edit

Edit your template definition, description or name as desired and when you are ready click the Save Template button

Deleting a Template

Click the Delete button next to the Template you want to delete and then click Yes to confirm the deletion

Default Templates

Terrakube creates the following default templates:

CLI-Driven Templates

Terrakube use job templates for all executions, Terrakube automatically create the following templates that are used when using the terraform remote state backend operations. This templates are created in all organizations.

Terraform Plan/Apply Cli Template

Will be used when you execute using the terraform cli

flow:
- type: "terraformPlan"
  name: "Terraform Plan from Terraform CLI"
  step: 100
- type: "approval"
  name: "Approve Plan from Terraform CLI"
  step: 150
  team: "TERRAFORM_CLI"
- type: "terraformApply"
  name: "Terraform Apply from Terraform CLI"
  step: 200

Terraform Plan/Destroy Cli Templates

Will be used when you execute terraform destroyusing the terraform cli

flow:
- type: "terraformPlanDestroy"
  name: "Terraform Plan Destroy from Terraform CLI"
  step: 100
- type: "approval"
  name: "Approve Plan from Terraform CLI"
  step: 150
  team: "TERRAFORM_CLI"
- type: "terraformApply"
  name: "Terraform Apply from Terraform CLI"
  step: 200

This templates can be updated if need it but in order for the terraform remote state backed to work properly the step number and the template names should not be changed. So if you delete or modify this templates

Persistent Context

Persistent Context is helpfull when you need to save information from the job execution, for example it can be used to save the infracost or save the thread id when using the Slack extension. We can also use it to save any JSON information generated inside Terrakube Jobs.

Using Persistent Contexts with the Terrakube API

In order to save the information the terrakube API exposes the following endpoint

POST {{terrakubeApi}}/context/v1/{{jobId}}
{
  "slackThreadId": "12345667",
  "infracost": {}
}

Job context can only be updated when the status of the Job is running.

To get the context you can use the Terrakube API

GET {{terrakubeApi}}/context/v1/{{jobId}}

Using Persistent Contexts in Templates

The persistent context can be used using the Context extension from the Terrakube extension repository. It supports saving a JSON file or saving a new property inside the context JSON.

import Context
        
new Context("$terrakubeApi", "$terrakubeToken", "$jobId", "$workingDirectory").saveFile("infracost", "infracost.json")
new Context("$terrakubeApi", "$terrakubeToken", "$jobId", "$workingDirectory").saveProperty("slackId", "1234567890")

This is an example of a Terrakube template using the persistent job context to save the infracost information.

flow:
- type: "terraformPlan"
  step: 100
  commands:
    - runtime: "GROOVY"
      priority: 100
      after: true
      script: |
        import Infracost

        String credentials = "version: \"0.1\"\n" +
                "api_key: $INFRACOST_KEY \n" +
                "pricing_api_endpoint: https://pricing.api.infracost.io"

        new Infracost().loadTool(
           "$workingDirectory",
           "$bashToolsDirectory", 
           "0.10.12",
           credentials)
        "Infracost Download Completed..."
    - runtime: "BASH"
      priority: 200
      after: true
      script: |
        terraform show -json terraformLibrary.tfPlan > plan.json 
        INFRACOST_ENABLE_DASHBOARD=true infracost breakdown --path plan.json --format json --out-file infracost.json
    - runtime: "GROOVY"
      priority: 300
      after: true
      script: |
        import Context
        
        new Context("$terrakubeApi", "$terrakubeToken", "$jobId", "$workingDirectory").saveFile("infracost", "infracost.json")

        "Save context completed..."

You can use persistent context to customize the Job UI, see UI templates for more details.

Import Templates

Templates can become big over time while adding steps to execute additional business logic.

Example before template import:

flow:
- type: "terraformPlan"
  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: |
        cd $workingDirectory
        terratag -tags="{\"environment_id\": \"development\"}"
- type: "terraformApply"
  step: 300

Terrakube supports having the template logic in an external git repository like the following:

This feature is only available from Terrakube 2.11.0

flow:
  - type: "terraformPlan"
    step: 100
    importComands:
      repository: "https://github.com/AzBuilder/terrakube-extensions"
      folder: "templates/terratag"
      branch: "import-template"
  - type: "terraformApply"
    step: 200

Using import templates become simply and we can reuse the logic accross several Terrakube organizations

The sample template can be found here.

The import commands are using a public repository, we will add support for private repositories in the future.

UI Templates

Terrakube allows you to customize the UI for each step inside your templates using standard HTML. So you can render any kind of content extracted from your Job execution in the Terrakube UI.

For example you can present the costs using Infracost in a friendly way:

Or present a table with the OPA policies

In order to use UI templates you will need to save the HTML for each template step using the Persistent Context. Terrakube expects the ui templates in the following format.

terrakubeUI :{
   "100" : "<span>Some Content</span>"
}

In the above example the 100 property in the JSON refers to the step number inside your template. In order to save this value from the template you can use the Context extension. For example:

flow:
  - type: "terraformPlan"
    step: 100
    name: "Plan"
    commands:
      - runtime: "GROOVY"
        priority: 300
        after: true
        script: |
          import Context
          
          def uiTemplate = '{"100":"<span>Simple Text</span>"}'
          new Context("$terrakubeApi", "$terrakubeToken", "$jobId", "$workingDirectory").saveProperty("terrakubeUI", uiTemplate)

          "Save context completed..."
  - type: "terraformApply"
    step: 200
    name: "Apply"

Filter global variables in jobs

In some special cases it is necesarry to filter the global variables used inside the job execution, if the "inpursEnv" or "inpustTerraform" is not defined all global variables will be imported to the job context.

Template Configuration

flow:
  - type: "customScripts"
    step: 100
    inputsEnv:
      INPUT_IMPORT1: $IMPORT1
      INPUT_IMPORT2: $IMPORT2
    commands:
      - runtime: "BASH"
        priority: 100
        before: true
        script: |
          echo $INPUT_IMPORT1
          echo $INPUT_IMPORT2

$IMPORT1 and $IMPORT2 will be added to the job context as env variable INPUT_IMPORT1 and INPUT_IMPORT2

Global Variables Setup

Running Workspace

Other configuration Options.

Import terraform variables

flow:
  - type: "customScripts"
    step: 100
    inputsTerraform:
      INPUT_IMPORT1: $IMPORT1
      INPUT_IMPORT2: $IMPORT2
    commands:
      ....

Import when importing the template

flow:
  - type: "terraformPlan"
    step: 100
    importComands:
      repository: "https://github.com/AzBuilder/terrakube-extensions"
      folder: "templates/terratag"
      branch: "import-template"
      inputsEnv:
        INPUT_IMPORT1: $IMPORT1
        INPUT_IMPORT2: $IMPORT2
      inputsTerraform:
        INPUT_IMPORT1: $IMPORT1
        INPUT_IMPORT2: $IMPORT2
  - type: "terraformApply"
    step: 200

Import Precedence

workspace env variables > importComands env variables > Flow env variables workspace terraform variables > importComands terraform variables > Flow terraform variables

Template Scheduling in Jobs

When we deploy some infrastructure we can set some other template to execute in some specific time for example to destroy the infrascturture or resize it.

This example will show the basic logic to accomplish but it is not creaing a real VM it just running some scripts that are showing the injected terraform variables when running the job.

Example

Define the size as global terraform variables for example SIZE_SMALL and SIZE_BIG, this terraform variables will be injected in our future templates "schedule1" and "schedule2" as terraform variables dynamically.

We define a job template that creates the infrasctucture using some small size and create two schedule at the end of the template.

Create Virtual Machine (Example)

flow:
  - type: "customScripts"
    step: 100
    inputsTerraform:
      SIZE: $SIZE_SMALL
    commands:
      - runtime: "BASH"
        priority: 100
        before: true
        script: |
          echo "SIZE : $SIZE"
  - type: "scheduleTemplates"
    step: 200
    templates:
      - name: "schedule1"
        schedule: "0 0/5 * ? * * *"
      - name: "schedule2"
        schedule: "0 0/10 * ? * * *"

This will create our "virtual machine" using size small, after it will set two addtional schedules to run every 5 and 10 minutes to resize it.

We will have 3 templates, one to create the virtual machine and two to resize it

Once the workspace is executed creating the infrasctructure two automatic shedules will be define

Differente jobs will be executed.

Resize Template (schedule1)

Inject the new size using global terraform variables

flow:
  - type: "customScripts"
    step: 100
    inputsTerraform:
      SIZE: $SIZE_SMALL
    commands:
      - runtime: "BASH"
        priority: 100
        before: true
        script: |
          echo "SIZE : $SIZE"

Resize Template (schedule2)

Inject the new size using global terraform variables

flow:
  - type: "customScripts"
    step: 100
    inputsTerraform:
      SIZE: $SIZE_BIG
    commands:
      - runtime: "BASH"
        priority: 100
        before: true
        script: |
          echo "SIZE : $SIZE"

Templates

Example 1:

flow:
  - name: "Plan"
    type: "terraformPlan"
    step: 100
  - name: "Apply"
    type: "terraformApply"
    step: 200

Example 2:

flow:
- type: "terraformPlanDestroy"
  name: "Terraform Plan Destroy from Terraform CLI"
  step: 100
- type: "approval"
  name: "Approve Plan from Terraform CLI"
  step: 150
  team: "TERRAFORM_CLI"
- type: "terraformApply"
  name: "Terraform Apply from Terraform CLI"
  step: 200

Example 3:

flow:
  - type: "terraformDestroy"
    step: 100
  - type: "disableWorkspace"
    step: 200

flow:
  - name: "Plan"
    type: "terraformPlan"
    step: 100
    commands:
      - runtime: "GROOVY"
        priority: 100
        before: true
        script: |
          @Grapes([
            @Grab('commons-io:commons-io:2.8.0'),
            @Grab('org.apache.commons:commons-compress:1.21'),
          ])

          import org.apache.commons.io.FileUtils
          
          class TerraTagDownloader {
            def downloadTerraTag(workingDirectory, version, os, arch) {
              String terraTagFile = "terratag_${version}_${os}_${arch}.tar.gz"
              String terraTagURL = "https://github.com/env0/terratag/releases/download/v${version}/${terraTagFile}"
              println "Downloading $terraTagURL"
              FileUtils.copyURLToFile(new URL(terraTagURL), new File("${workingDirectory}/${terraTagFile}"))
            }
          } 
          new TerraTagDownloader().downloadTerraTag("$workingDirectory", "0.1.29", "darwin", "amd64")
          "TerraTag Download Compledted..."
      - runtime: "BASH"
        priority: 200
        before: true
        script: |
          cd $workingDirectory;
          tar -xvf terratag_0.1.29_darwin_amd64.tar.gz;
          chmod +x terratag;
          ./terratag -tags="{\"environment_id\": \"development\"}"
  - name: "Apply"
    type: "terraformApply"
    step: 300
  - name: "Destroy"
    type: "terraformDestroy"
    step: 400

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

If you notice the above script is more compact as is reusing some logic. If you want to simplify and reuse some templates in your organization, please check Import Templates.

Using Templates you can even customize the UI for each job, see UI templates for more details.

Persistent Context

If you need to store information generated on the steps defined in your template, you can use persistent context.

Creating a Template

Manage VCS Templates permission is required to perform this action, please check Team Management for more info

Once you are in the desired organization, click the Settings button, then in the left menu select the Templates option and click the Add Template button

You will see a list of some predefined templates than you can utilize as a quick start or if you prefer you can click the Blank Template to start from scratch

In the next screen you can define your template and when you are ready click the Continue button.

Finally, you can assign a name and description to your template and click the Create Template button.

Now you template is ready and you can start using it in any workspace within your organization.

By default Terrakube don't create any template, so you have to define the templates in your organization based on your requirements.

Editing a Template

Click the Edit button next to the Template you would like to edit

Edit your template definition, description or name as desired and when you are ready click the Save Template button

Deleting a Template

Click the Delete button next to the Template you want to delete and then click Yes to confirm the deletion