Terrakube has two kinds of API tokens: user and team. Each token type has a different access level and creation process, which are explained below.

API tokens are only shown once when you create them, and then they are hidden. You have to make a new token if you lose the old one.

User API Tokens

API tokens may belong directly to a user. User tokens inherit permissions from the user they are associated with.

User API tokens can be generated inside the User Settings.

Click the Generate and API token button

Add some small description to the token and the duration

The new token will be showed and you can copy it to star calling the Terrakube API using Postman or some other tool.

Delete API Tokens

To delete an API token, navigate to the list of tokens, click the Delete button next to the token you wish to remove, and confirm the deletion.

Team API Tokens

API tokens may belong to a specific team. Team API tokens allow access Terrakube, without being tied to any specific user.

To manage the API token for a team, go to Settings > Teams > Edit button on the desired team.

Click the Create a Team Token button in the Team API Tokens section.

Add the token description and duration and click the Generate token button

The new token will be showed and you can copy it to star calling the Terrakube API using Postman or some other tool.

Delete Team API Tokens

To delete an API token, navigate to the list of tokens, click the Delete button next to the token you wish to remove, and confirm the deletion.

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.

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.

Persistent Context

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

Creating a Template

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.

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

Organizations are privately shared spaces for teams to collaborate on infrastructure. Basically are logical containers that you can use to define your company hierarchy to organize the workspaces, modules in the private registry and assign fine grained permissions to your teams.

In this section:

Click the organizations list on the main menu and then click the Create new organization button

Provide organization name and description and click the Create organization button

Then you will redirected to the Organization Settings page where you can define your teams, this is step is important so you can assign the permissions to users, otherwise you won't be able to create workspaces and modules inside the organization.

In Terrakube you can define user permissions inside your organization using teams.

Creating a Team

Once you are in the desired organization, click the Settings button and then in the left menu select the Teams option.

Click the Create team button

In the popup, provide the team name and the permissions assigned to the team. Use the below table as reference:

Finally click the Create team button and the team will be created

Now all the users inside the team will be able to manage the specific resources within the organization based on the permissions you grantted.

Edit a Team

Click the Edit button next to the team you want to edit

Change the permissions you need and click the Save team button

Delete a Team

Click the Delete button next to the team you want to delete, and then click the Yes button to confirm the deletion. Please take in consideration the deletion is irreversible

Global Variables allow you to define and apply variables one time across all workspaces within an organization. For example, you could define a global variable of provider credentials and automatically apply it to all workspaces.

Creating a Global Variable

Once you are in the desired organization, click the Settings button, then in the left menu select the Global Variables option and click the Add global variable button

In the popup, provide the required values. Use the below table as reference:

Finally click the Save global variable button and the variable will be created

You will see the new global variable in the list. And now the variable will be injected in all the workspaces within the organization

Edit a Global Variable

Click the Edit button next to the global variable you want to edit.

Change the fields you need and click the Save global variable button

Delete a Global Variable

Click the Delete button next to the global variable you want to delete, and then click the Yes button to confirm the deletion. Please take in consideration the deletion is irreversible

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": {}
}

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.

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

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 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:

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.

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)

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

Resize Template (schedule2)

Inject the new size using global terraform variables

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:

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.

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 terraform apply 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

You can use tags to categorize, sort, and even filter workspaces based on the tags.

You can manage tags for the organization in the Settings panel. This section lets you create and remove tags. Alternatively, you can add existing tags or create new ones in the .

Creating a Tag

Once you are in the desired organization, click the Settings button, then in the left menu select the Tags option and click the Add global variable button

In the popup, provide the required values. Use the below table as reference:

Finally click the Save tag button and the variable will be created

You will see the new tag in the list. And now you can use the tag in the workspaces within the organization

Edit a Tag

Click the Edit button next to the tag you want to edit.

Change the fields you need and click the Save tag button

Delete a Tag

Click the Delete button next to the tag you want to delete, and then click the Yes button to confirm the deletion. Please take in consideration the deletion is irreversible and the tag will be removed from all the workspaces using it.