When working with Terraform at Enterprise level, you need to organize your infrastructure in different collections. Terrakube manages infrastructure collections with workspaces. A workspace contains everything Terraform needs to manage a given collection of infrastructure, so you can easily organize all your resources based in your requirements.

For example, you can create a workspace for dev environment and a different workspace for production. Or you can separate your workspaces based in your resource types, so you can create a workspace for all your SQL Databases and anothers workspace for all your VMS.

You can create unlimited workspaces inside each Terrakube Organization. In this section:

When creating a Workspace, Terrakube supports 3 workflows types and based on the selected workflow you will need to provide some parameters. Please refer to each workflow section for more reference.

• Version Control workflow: Store your Terraform configuration in a git repository, and trigger runs based on pull requests and merges.

• CLI-driven workflow: Trigger remote Terraform runs from your local command line.

• API-driven workflow: A more advanced option. Integrate Terraform into a larger pipeline using the Terrakube API.

Version Control workflow

Click Workspaces in the main menu and then click the New workspace button

Select the IaC type for now we support terraform and open tofu

Choose the Version control workflow

Select an existing version control provider or click Connect to a different VCS to configure a new one. See VCS Providers for more details.

Provide the git repository URL and click the Continue button.

Configure the workspace settings.

Once you fill the settings click the Create Workspace button.

When using a VCS workflow you can select which branches, folder and action (aka, Default template (VCS push)) the runs will be triggered from when a git push action happens.

The VCS branches accepts a list of branches separated by comma, the first in the list is used as the default for the runs kicked off from UI. The branches are compared as prefixes against the branch included in the payload sent from VCS provider.

You will be redirected to the Workspace page

And if you navigate to the Workspace menu, you will see the workspace in the Workspaces list

Once you create your workspace, Terrakube sets up a webhook with your VCS. This webhook runs a job based on the selected template every time you push new changes to the set workspace branches. However, this feature does not work yet with Azure DevOps VCS provider.

CLI-driven Workflow

Click Workspaces in the main menu and then click the New workspace button

Choose the CLI-driven workflow

Configure the workspace settings.

Once you fill the settings click the Create Workspace button.

You will be redirected to the Workspace page.

And if you navigate to the Workspace menu you will see the workspace in the Workspaces list

API-driven Workflow

Click Workspaces in the main menu and then click the New workspace button

Choose the API-driven workflow

Configure the workspace settings.

Once you fill the settings click the Create Workspace button.

ou will be redirected to the Workspace page.

And if you navigate to the Workspace menu you will see the workspace in the Workspaces list

Terrakube support sharing the terraform state between workspaces using the following data block.

data "terraform_remote_state" "remote_creation_time" {
  backend = "remote"
  config = {
    organization = "simple"
    hostname = "8080-azbuilder-terrakube-vg8s9w8fhaj.ws-us102.gitpod.io"
    workspaces = {
      name = "simple_tag1"
    }
  }
}

For example it can be used in the following way:

data "terraform_remote_state" "remote_creation_time" {
  backend = "remote"
  config = {
    organization = "simple"
    hostname = "8080-azbuilder-terrakube-vg8s9w8fhaj.ws-us102.gitpod.io"
    workspaces = {
      name = "simple_tag1"
    }
  }
}

resource "null_resource" "previous" {}

resource "time_sleep" "wait_30_seconds" {
  depends_on = [null_resource.previous]

  create_duration = data.terraform_remote_state.remote_creation_time.outputs.creation_time
}

resource "null_resource" "next" {
  depends_on = [time_sleep.wait_30_seconds]
}

The workspace overview page provides you a summary of the current workspace state.

Managing Workspace Tags

You can manage tags for the workspace in the overview page. The right panel lets you search existing tags or type a new tag name to add or remove tags from the workspace.

Each Terrakube workspace has its own separate state data, used for jobs within that workspace. In Terrakube you can see the Terraform state in the standard JSON format provided by the Terraform cli or you can see a Visual State, this is a diagram created by Terrakube to represent the resources inside the JSON state.

JSON State

Go to the workspace and click the States tab and then click in the specific state you want to see.

You will see the state in JSON format

You can click the Download button to get a copy of the JSON state file

Visual State

Inside the states page, click the diagram tab and you will see the visual state for your terraform state.

The visual state will also show some information if you click each element like the following:

Resources

All the resources can be shown in the overview page inside the workspace:

If you click the resources you can check the information about each resouce like the folloing

Terrakube workspace variables let you customize configurations and store information like static provider credentials. You can also reference this variables inside your Templates.

You can set variables specifically for each workspace or you can create Global Variables to reuse the same variables across multiple workspaces.

Workspace-Specific Variables

To view and manage a workspace's variables, go to the workspace and click the Variables tab.

The Variables page appears, showing all workspace-specific variables. This is where you can add, edit, and delete workspace-specific variables.

There are 2 kinds of Variables:

• Terraform Variables

• Environment Variables

Terraform Variables

These Terraform variables are set using a terraform.tfvars file. To use interpolation or set a non-string value for a variable, click its HCL checkbox.

Add a Terraform Variable

Go to the workspace Variables page and in the Terraform Variables section click the Add variable button.

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

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

Edit a Terraform Variable

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

Make any desired changes and click Save variable.

Delete a Terraform Variable

Click the Delete button next to the variable you want to delete.

Click Yes to confirm your action.

Environment Variables

These variables are set in Terraform's shell environment using export.

Add an Environment Variable

Go to the workspace Variables page and in the Environment Variables section click the Add variable button.

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

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

Edit an Environment Variable

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

Make any desired changes and click Save variable.

Delete an Environment Variable

Click the Delete button next to the variable you want to delete.

Click Yes to confirm your action.

Requirements

The dynamic provider credential setup in AWS can be done with the Terrraform code available in the following link:

https://github.com/AzBuilder/terrakube/tree/main/dynamic-credential-setup/aws

Make sure to mount your public and private key to the API container as explained here

Validate the following terrakube api endpoints are working:

• https://terrakube-api.mydomain.com/.well-known/jwks

• https://terrakube-api.mydomain.com/.well-known/openid-configuration

Set terraform variables using: "variables.auto.tfvars"

terrakube_token = "TERRAKUBE_PERSONAL_ACCESS_TOKEN"
terrakube_api_hostname = "TERRAKUBE-API.MYCLUSTER.COM"
terrakube_federated_credentials_audience="aws.workload.identity"
terrakube_organization_name="simple"
terrakube_workspace_name = "dynamic-workspace-aws"
aws_region = "us-east-1"

Run Terraform apply to create all the federated credential setup in AWS and a sample workspace in terrakube for testing

To test the following terraform code can be used:

terraform {

  cloud {
    organization = "terrakube_organization_name"
    hostname = "terrakube-api.mydomain.com"

    workspaces {
      name = "terrakube_workspace_name"
    }
  }
}

provider "aws" {


}

resource "aws_s3_bucket" "example" {
  bucket = "my-tf-superbucket-awerqerq"

  tags = {
    Name        = "My bucket"
    Environment = "Dev"
  }
}

In progress

Terrakube allows to schedule a job inside workspaces, this will allow to execute a specific template in an specific time.

To create a workspace schedule click the "schedule" tab and click "Add schedule" like the following image.

This is usefull for example when you want to destroy your infrastructure by the end of every week to save some money with your cloud provider and recreate it every monday morning.

Example.

Lets destroy the workspace every friday at 6 pm

Lets create the workspace every monday at 5:30 am

Requirements

The dynamic provider credential setup in GCP can be done with the Terrraform code available in the following link:

Make sure to mount your public and private key to the API container as explained

Validate the following terrakube api endpoints are working:

Set terraform variables using: "variables.auto.tfvars"

Run Terraform apply to create all the federated credential setup in GCP and a sample workspace in terrakube for testing

To test the following terraform code can be used:

Running Example

Requirements

The dynamic provider credential setup in Azure can be done with the Terrraform code available in the following link:

Make sure to mount your public and private key to the API container as explained

Validate the following terrakube api endpoints are working:

Set terraform variables using: "variables.auto.tfvars"

Run Terraform apply to create all the federated credential setup in AWS and a sample workspace in terrakube for testing

To test the following terraform code can be used:

Running Example:

When running a job Terrakube will correctly authenticate to Azure without any credentials inside the workspace

Generate Public and Private Key.

To use Dynamic Provider credentials we need to genera a public and private key that will be use to generate a validate the federated tokens, we can use the following commands

openssl genrsa -out private_temp.pem 2048
openssl rsa -in private_temp.pem -outform PEM -pubout -out public.pem

You need to make sure the private key starts with "-----BEGIN PRIVATE KEY-----" if not the following command can be used to transform the private key to the correct format

openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private_temp.pem -out private.pem

The public and private key need to be mounted inside the container and the path should be specify in the following environment variables

• DynamicCredentialPublicKeyPath

• DynamicCredentialPrivateKeyPath

Public Endpoints Requirements

To use Dynamic Provider credentials the following public endpoints were added. This endpoint needs to be accessible for your different cloud providers.

GET https://TERRAKUBE.MYSUPERDOMAIN.COM/.well-known/openid-configuration
{
  "issuer": "https://TERRAKUBE.MYSUPERDOMAIN.COM",
  "jwks_uri": "https://TERRAKUBE.MYSUPERDOMAIN.COM/.well-known/jwks",
  "response_types_supported": [
    "id_token"
  ],
  "claims_supported": [
    "sub",
    "aud",
    "exp",
    "iat",
    "iss",
    "jti",
    "terrakube_workspace_id",
    "terrakube_organization_id",
    "terrakube_job_id"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ]
}

GET https://TERRAKUBE.MYSUPERDOMAIN.COM/.well-known/jwks
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "n": "ALEzGE4Rn2WhxOhIuXAzq7e-WvRLCJfoqrHMUXtpt6gefNmWGo9trbea84KyeKdvzE9wBwWxnz_U5d_utmLLztVA2FLdDfnndh7pF4Fp7hB-lhaT1hV2EsiFsc9oefCYmkzXmHylfNQOuqNlRA_2Xu5pHovrF79WW01hWSjhGTkpj6pxFG4t7Tl54SWnJ83CvGDAKuoO9c1M1iTKikB3ENMK8WfU-wZJ4oLTAfhSydqZxZuGRhiwPGsEQOpRynyHJ54XWZHmFdsWs_eGRsfs1iTPbiQSBZbaEwz36HF4QdqFzzLGd67sTtZku_YEsUbJW8cbK6nOFEdR0BSTtSV-lPk=",
      "e": "AQAB",
      "kid": "03446895-220d-47e1-9564-4eeaa3691b42",
      "alg": "RS256"
    }
  ]
}

Terrakube Environment Variables:

The following environment variables can be used to customize the dynamic credentials configuration:

• DynamicCredentialId = This will be the kid in the JWKS endpoint (Default value: 03446895-220d-47e1-9564-4eeaa3691b42)

• DynamicCredentialTtl= The TTL for the federated token generated internally in Terrakube (Defafult: 30)

• DynamicCredentialPublicKeyPath= The path to the public key to validate the federated tokens

• DynamicCredentialPrivateKeyPath=The path to the private key to generate the federated tokens

Token structure

Terrakube will generate a JWT token internally, this token will be used to authenticate to your cloud provider.

The token structure looks like the following for Azure

JWT HEADER
{
  "kid": "12345",
  "alg": "RS256"
}
JWT BODY
{
  "sub": "organization:TERRAKUBE_ORG_NAME:workspace:TERRAKUBE_WORKSPACE_NAME",
  "aud": "api://AzureADTokenExchange",
  "jti": "12345678",
  "terrakube_workspace_id": "1",
  "terrakube_organization_id": "2",
  "terrakube_job_id": "3",
  "iat": 1713397293,
  "iss": "https://terrakube-api.example.com",
  "exp": 1713397353
}
SIGNATURE

The token structure looks like the following for GCP

JWT HEADER
{
  "kid": "03446895-220d-47e1-9564-4eeaa3691b42",
  "alg": "RS256"
}
JWT BODY
{
  "sub": "organization:TERRAKUBE_ORG_NAME:workspace:TERRAKUBE_WORKSPACE_NAME",
  "aud": "https://iam.googleapis.com/projects/xxxxx/locations/global/workloadIdentityPools/xxxxx/providers/xxxxx",
  "jti": "d4432299-5dad-4b1e-9756-544639e84cec",
  "terrakube_workspace_id": "d9b58bd3-f3fc-4056-a026-1163297e80a8",
  "terrakube_organization_id": "8abe206b-29a8-4ed8-8a3b-30237e295659",
  "terrakube_job_id": "1",
  "iat": 1713915600,
  "iss": "https://terrakube-api.example.com",
  "exp": 1713917400
}
SIGNATURE

The token structure looks like the following for AWS

JWT HEADER
{
  "kid": "03446895-220d-47e1-9564-4eeaa3691b42",
  "alg": "RS256"
}
JWT BODY
{
  "sub": "organization:TERRAKUBE_ORG_NAME:workspace:TERRAKUBE_WORKSPACE_NAME",
  "aud": "aws.workload.identity",
  "jti": "d4432299-5dad-4b1e-9756-544639e84cec",
  "terrakube_workspace_id": "d9b58bd3-f3fc-4056-a026-1163297e80a8",
  "terrakube_organization_id": "8abe206b-29a8-4ed8-8a3b-30237e295659",
  "terrakube_job_id": "1",
  "iat": 1713915600,
  "iss": "https://terrakube-api.example.com",
  "exp": 1713917400
}
SIGNATURE

With the CLI integration, you can use Terrakube’s collaboration features in the Terraform CLI workflow that you are already familiar with. This gives you the best of both worlds as a developer who uses the Terraform CLI, and it also works well with your existing CI/CD pipelines.

You can initiate runs with the usual terraform plan and terraform apply commands and then monitor the run progress from your terminal. These runs run remotely in Terrakube.

Configuration

To use the CLI-driven workflow the firts step will be to setup our project to use the terraform remote backend or the cloud block as the following example:

terraform {
  backend "remote" {
    hostname = "terrakube-api.example.com"
    organization = "simple"
    workspaces {
      name = "workspace1"
    }
  }
}

resource "random_string" "random" {
  length           = 16
  special          = true
  override_special = "/@£$"
}

terraform {
  cloud {
    organization = "simple"
    hostname = "terrakube-api.example.com"
    workspaces {
      name = "samplecloud"
    }
  }
}

resource "random_string" "random" {
  length           = 16
  special          = true
  override_special = "/@£$"
}

terraform {
  cloud {
    organization = "simple"
    hostname = "terrakube-api.example.com"

    workspaces {
      tags = ["development", "networking"]
    }
  }
}

resource "random_string" "random" {
  length           = 16
  special          = true
  override_special = "/@£$"
}

• Hostname

  • This should be the Terrakube API

• Organization

  • This should be the Terrakube organization where the workspace will be created.

• Workspace

  • The name of the workspace to be created. Or you can use an existing workspace created in the UI using the API or CLI driven workflow.

Terraform login.

Once we have added the terraform remote state configuration we will need to authenticate to Terrakube using the following command with the Terrakube API as the following:

terraform login 8080-azbuilder-terrakube-3xqsq270uq1.ws-us82.gitpod.io

The output will look something like the following:

terraform login 8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io
Terraform will request an API token for 8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io using OAuth.

This will work only if you are able to use a web browser on this computer to
complete a login process. If not, you must obtain an API token by another
means and configure it in the CLI configuration manually.

If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
    C:\Users\XXXXXX\AppData\Roaming\terraform.d\credentials.tfrc.json

Do you want to proceed?
  Only 'yes' will be accepted to confirm.

  Enter a value: yes

Terraform must now open a web browser to the login page for 8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io.

If a browser does not open this automatically, open the following URL to proceed:
    https://5556-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io/dex/auth?scope=openid+profile+email+offline_access+groups&client_id=example-app&code_challenge=YYe059U9HyeMy1-RmuEzSajPJYGdcY4IkNr0pZz4LZ8&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A10000%2Flogin&response_type=code&state=f8b6da79-35f3-2b92-d8d8-179cda386f91

Terraform will now wait for the host to signal that login was successful.


---------------------------------------------------------------------------------

Success! Terraform has obtained and saved an API token.

The new API token will be used for any future Terraform command that must make
authenticated requests to 8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io.

Terraform Init

After the authentication is completed you can run the following command to initialized the workspace

terraform init

The output will look like this:

terraform init

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/random from the dependency lock file
- Using previously-installed hashicorp/random v3.4.3

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

If the initialization is successfull you should be able to see something like this:

Implicit Workspace Creation

Terrakube will create a new workspace with the name you specify in the cloud block if it doesn’t already exist in your organization. You will see a message about this when you run terraform init.

Terraform Plan

Once the terraform initialization is completed we should be able to run a terraform plan remotely using the following:

terraform plan

Running plan in the remote backend. Output will stream here. Pressing Ctrl-C
will stop streaming the logs, but will not stop the plan running remotely.

Preparing the remote plan...

To view this run in a browser, visit:
https://8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io/app/simple/workspace1/runs/1

Waiting for the plan to start...

Terrakube Remote Plan Execution



Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # random_string.random will be created
  + resource "random_string" "random" {
      + id               = (known after apply)
      + length           = 16
      + lower            = true
      + min_lower        = 0
      + min_numeric      = 0
      + min_special      = 0
      + min_upper        = 0
      + number           = true
      + numeric          = true
      + override_special = "/@£$"
      + result           = (known after apply)
      + special          = true
      + upper            = true
    }

Plan: 1 to add, 0 to change, 0 to destroy.

If you go to the Terrakube UI, you will be able to see the workspace plan execution.

Terraform Apply

You can also execute a terraform apply and it will run inside Terrakube remotely.

terraform apply
Running apply in the remote backend. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.

Preparing the remote apply...

To view this run in a browser, visit:
https://8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io/app/simple/workspace1/runs/2

Waiting for the plan to start...

Terrakube Remote Plan Execution



Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # random_string.random will be created
  + resource "random_string" "random" {
      + id               = (known after apply)
      + length           = 16
      + lower            = true
      + min_lower        = 0
      + min_numeric      = 0
      + min_special      = 0
      + min_upper        = 0
      + number           = true
      + numeric          = true
      + override_special = "/@£$"
      + result           = (known after apply)
      + special          = true
      + upper            = true
    }

Plan: 1 to add, 0 to change, 0 to destroy.


Do you want to perform these actions in workspace "workspace1"?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

random_string.random: Creating...
random_string.random: Creation complete after 0s [id=QvsEmtO7WoeJJcAJ]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Terraform Destroy

Executing the terraform destroy is also possible.

terraform destroy
Running apply in the remote backend. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.

Preparing the remote apply...

To view this run in a browser, visit:
https://8080-azbuilder-terrakube-po7evw1u15x.ws-us86.gitpod.io/app/simple/workspace1/runs/3

Waiting for the plan to start...

Terrakube Remote Plan Execution


random_string.random: Refreshing state... [id=QvsEmtO7WoeJJcAJ]

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # random_string.random will be destroyed
  - resource "random_string" "random" {
      - id               = "QvsEmtO7WoeJJcAJ" -> null
      - length           = 16 -> null
      - lower            = true -> null
      - min_lower        = 0 -> null
      - min_numeric      = 0 -> null
      - min_special      = 0 -> null
      - min_upper        = 0 -> null
      - number           = true -> null
      - numeric          = true -> null
      - override_special = "/@£$" -> null
      - result           = "QvsEmtO7WoeJJcAJ" -> null
      - special          = true -> null
      - upper            = true -> null
    }

Plan: 0 to add, 0 to change, 1 to destroy.


Do you really want to destroy all resources in workspace "workspace1"?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

random_string.random: Destroying... [id=QvsEmtO7WoeJJcAJ]
random_string.random: Destruction complete after 0s

Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

Inside the UI the terraform destroy operation will look like this.

The following will show how easy is to implement an ephemeral workspace using Terrakube custom schedules and templates with the remote CLI-driven workflow.

The first step will be to create a new organization, lets call it "playground".

Once we have the playground organization, we need to add a team with access to create templates like the following:

We will also need a team with access to create/delete a workspace only, like the following:

Once we have the two teams in our new playground organization, we can proceed and create a new template that we will be using to auto destroy all the workspace:

Lets call it "delete-playground" and it will have the following code:

flow:
  - type: "terraformDestroy"
    name: "Destroy Playground"
    step: 100
  - type: "disableWorkspace"
    name: "Delete Workspace"
    step: 200

Now we can update the default template that is used when we are using the remote CLI-driven workflow, this template is inside every organization by default and is called "Terraform-Plan/Apply-Cli", usually we don't need to update this template but we will do some small changes to enable ephemeral workspaces in the playground organization.

We need to go the the templates inside the organization settings and edit the template

We will add a new step in the template, this will allow to schedule a job that will be using the "delete-playground" template that we have created above.

We need to use the following template code:

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
- type: "scheduleTemplates"
  step: 300
  name: "Setup auto destroy"
  templates:
    - name: "delete-playground"
      schedule: "0 0/5 * ? * * *"

If we pay special attention we just add a new section where we define that the schedule will run every five minutes after the Terraform apply is completed.

In this example we will schedule the template every five minutes for testing purposes.

  name: "Setup auto destroy"
  templates:
    - name: "delete-playground"
      schedule: "0 0/5 * ? * * *"

Now we need to define our Terraform code, lets use the following simple example:

terraform {
  cloud {
    organization = "playground"
    hostname = "8080-azbuilder-terrakube-h128dcdc7l1.ws-us105.gitpod.io"

    workspaces {
      tags = ["myplayground", "example"]
    }
  }
}

resource "null_resource" "previous" {}

resource "time_sleep" "wait_5_seconds" {
  depends_on = [null_resource.previous]

  create_duration = "5s"
}

resource "null_resource" "next" {
  depends_on = [time_sleep.wait_5_seconds]
}

output "creation_time" {
    value = time_sleep.wait_5_seconds.create_duration
}

Run terraform login to connect to our Terrakube instance:

terraform login 8080-azbuilder-terrakube-h128dcdc7l1.ws-us105.gitpod.io

Now we can run terraform init to initialize our workspace inside the playground organization, lets use "myplayground" for the name of our new workspace

Let's run terraform apply and create our resources:

Preparing the remote apply...

To view this run in a browser, visit:
https://8080-azbuilder-terrakube-h128dcdc7l1.ws-us105.gitpod.io/app/playground/myplayground/runs/1

Waiting for the plan to start...

***************************************
Running Terraform PLAN
***************************************

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # null_resource.next will be created
  + resource "null_resource" "next" {
      + id = (known after apply)
    }

  # null_resource.previous will be created
  + resource "null_resource" "previous" {
      + id = (known after apply)
    }

  # time_sleep.wait_5_seconds will be created
  + resource "time_sleep" "wait_5_seconds" {
      + create_duration = "5s"
      + id              = (known after apply)
    }

Plan: 3 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + creation_time = "5s"

Do you want to perform these actions in workspace "myplayground"?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

null_resource.previous: Creating...
null_resource.previous: Creation complete after 0s [id=7198759863280029870]
time_sleep.wait_5_seconds: Creating...
time_sleep.wait_5_seconds: Creation complete after 5s [id=2023-10-18T16:05:14Z]
null_resource.next: Creating...
null_resource.next: Creation complete after 0s [id=855270182201609076]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

creation_time = "5s"

Our new workspace is created and if we go the organization we can see all the information

The job will be running to create the resources:

We can see that our job is completed and the setup auto destroy have created a new schedule for our workspace:

We could go to the schedules tab:

This schedule will run in 5 minutes:

After waiting for 5 minutes we will see that Terrakube have created a new Job automatically

If we check the details for the new job we can see that a terraform destroy will be executed:

All of the workspace resources are deleted and the workspace will be deleted automatically after the destroy is completed.

Once the Job is completed, our workspace information is deleted from Terrakube

If we are using AWS, AZURE, GCP or any other terraform provider that allow to inject the credentials using environment variables we could use "global variables" to define those.

Global variables will be injected automatically to any workspace inside the playground organization.

In this section:

Hello Actions

Let's start writing our Hello World action. This action will include a single button with the text "Quick Start".

As you can see, an action is essentially some JavaScript code, specifically a React component. If you are not familiar with JavaScript and React, I recommend before continuing.

This component contains only one button and receives a context parameter. We will discuss more about the context later. For now, you only need to know that the context provides some data related to the area where the action will appear.

Terrakube uses , so by default, all antd components are available when you are developing an action.

Testing our Hello world action

To create the action in your Terrakube instance, navigate to the Organization settings and click the Create Action button

Add the following data and click the save button.

If you go to any workspace, the quick start button should appear.

Adding Interaction to the Action

Now let's add some interaction to the button. In the next example, we will use the Ant Design Messages component.

Now, if you update the action code, navigate to any workspace, and click the Quick Start button, you will see the Hello Actions message.

Using the context to access workspace data

For our quick start action, we will add the name of the workspace to the message.

Update the action code using the code above, click the Quick Start button, and you will see the message now displays the Workspace Name.

Using display criteria

f you view a couple of workspaces in the organization, you will see the "Quick Start" button always appears. This is useful if your action serves a general purpose, but there are scenarios where you want to display the action only for workspaces in a specific organization, with a specific version of Terraform, and so on.

In those cases, you will use display criteria, which provides a powerful way to decide when an action will appear or not. If you remember, we set the display criteria to true before. Now let's modify the criteria to show the action only if the workspace contains a specific name.

Navigate to the Actions settings and change the display criteria to:

(You can use another workspace name if you don't have the "sample_simple" workspace.)

Now the button will appear only for the sample_simple workspace. If you notice, the display criteria is a conditional JavaScript code. So you can use any JavaScript code to display the action based on a regular expression, for organizations starting with certain names, or even combine multiple conditions.

At this moment, our action only interacts with Terrakube data. However, a common requirement is to access other APIs to get some data, for example, to connect to the GitHub API to get the issues related to the workspace, or to connect to a cloud provider to interact with their APIs.

In these cases, we can make use of the Action Proxy. The proxy provides a way to connect to other backend services without needing to directly configure CORS for the API. The proxy also provides a secure way to use credentials without exposing sensitive data to the client.

Let's add a simple interaction using mock data from the JSONPlaceholder API that reads the comments from a post.

Now if you click the Quick Start button, you will see a dialog with the comments data from the API. The proxy allows to interact with external apis and securely manage credentials. To know more about the Actions proxy check the documentation.

Summary

Terrakube actions allow you to extend the UI in Workspaces, functioning similarly to plugins. These actions enable you to add new functions to your Workspace, transforming it into a hub where you can monitor and manage your infrastructure and gain valuable insights. With Terrakube actions, you can quickly observe your infrastructure and apply necessary actions.

Key Benefits of Terrakube Actions:

• Extend Functionality: Customize your Workspace with additional functions specifics to your needs.

• Monitor Infrastructure: Gain real-time insights into your infrastructure with various metrics and monitoring tools.

• Manage Resources: Directly manage and interact with your resources from within the Workspace.

• Flexibility: Quickly disable an action if it is not useful for your organization or set conditions for actions to appear, such as if a resource is hosted in GCP or if the workspace is Dev.

• Cloud-Agnostic Hub: Manage multi-cloud infrastructure from a single point, providing observability and actionability without needing to navigate individual cloud portals.

Examples of Terrakube Actions:

• Manage Infrastructure: Restart your Azure VM or add an action to quickly navigate to the resource in the Azure portal directly from Terrakube.

• Monitor Metrics: Track and display resource metrics for performance monitoring using tools like Prometheus, Azure Monitor or AWS Cloudwatch.

• Integrate with Tools: Seamlessly integrate with tools like Infracost to display resource and Workspace costs.

• AI Integration: Use AI to diagnose issues in your Workspaces. By integrating with models like OpenAI, Claude, and Gemini, you can quickly resolve errors in your infrastructure.

• Project and Incident Management: Integrate with Jira, GitHub Issues, and ServiceNow to identify Workspaces with pending work items or reported errors.

• Documentation: Link your Confluence documentation or wiki pages in your preferred tool, allowing quick access to documents related to your Workspace infrastructure.

Built-in Actions

Developing Actions

Creating an Action

After you develop your action. To create a new action in Terrakube:

1. Navigate to the settings in any Terrakube organization.

1. Click the Add Action button.

1. Provide the required information as detailed in the table below:

1. Click the Save button.

The context object contains data related to the Workspace that you can use inside the action. The properties depends on the .

context.workspace

Contains the workspace information in the Terrakube api format. See the for more details on the properties available.

Examples

• context.workspace.id: Id of the workspace

• context.workspace.attributes.name: Name of the workspace

• context.workspace.attributes.terraformVersion: Terraform version

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.settings

Contains the settings that you configured in the display criteria.

Examples

• context.settings.Repository: the value of repository that you set for the setting. Example:

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.state

For workspace/action this property contains the full terraform or open tofu state. For workspace/resourcedrawer/action and workspace/resourcedrawer/tab contains only the section of the resource

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

context.apiUrl

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

Display Criteria offer a flexible way to determine when an action will appear. While you can add logic inside your component to show or hide the action, using display criteria provides additional advantages:

• Optimize Rendering: Save on the loading cost of each component.

• Multiple Criteria: Add multiple display criteria based on your requirements.

• Conditional Settings: Define settings to be used when the criteria are met.

A display criteria is a JavaScript condition where you can use the data from the t to decide if the action will appear.

Examples

Always display the action

Display the action for Workspaces with specific Terraform version.

Display the action for Azure resources

Display the action only for Azure VM

Display Criteria Settings

You can set specific settings for each display criteria, which is useful when the action provides configurable options. For example, suppose you have an action that queries GitHub issues using the GitHub API and you want to display the issues using GraphQL. Your issues are stored in two different repositories: one for production and one for non-production.

In this case, you can create settings based on the display criteria to select the repository name. This approach allows your action code to be reusable. You only need to change the settings based on the criteria, rather than modifying the action code itself.

For instance:

• Production Environment: For workspaces starting with prod, use the repository name for production issues.

• Non-Production Environment: Use the repository name for non-production issues

By setting these configurations, you ensure that your action dynamically adapts to different environments or conditions, enhancing reusability and maintainability.

Sensitive Settings

For example, instead of directly storing an API key in the settings, you can reference a variable:

• For the development environment: ${{var.dev_api_key}}

• For the production environment: ${{var.prod_api_key}}

For the previous example, you will need to create the variables at workspace level or use global variables with the names dev_api_keyand prod_api_key

Multiple Display Actions

You can define multiple display criteria for your actions. In this case, the first criteria to be met will be applied, and the corresponding settings will be provided via the context.

Action Types define where an action will appear in Terrakube. Here is the list of supported types:

Workspace/Action

The action will appear on the Workspace page, next to the Lock button. Actions are not limited to buttons, but this section is particularly suitable for adding various kinds of buttons. Use this type for actions that involves interaction with the Workspace

Workspace/ResourceDrawer/Action

The action will appear for each resource when you click on a resource using the Overview Workspace page or the Visual State Diagram. Use this when an action applies to specific resources, such as restarting a VM or any actions that involve interaction with the resource.

Workspace/ResourceDrawer/Tab

The action will appear for each resource when you click on a resource using the Overview Workspace page or the Visual State Diagram. Use this when you want to display additional data for the resource, such as activity history, costs, metrics, and more.

For this type, theLabel property will be used as the name of the Tab pane.

The following actions are added by default in Terrakube. However, not all actions are enabled by default. Please refer to the documentation below if you are interested in activating these actions.

General

• Open Documentation: Adds a button to quickly navigate to the Terraform registry documentation for a specific resource.

• Resource Details: Adds a new panel to visualize the state attributes and dependencies for a resource.

Azure

• Open in Azure Portal: Adds a button to quickly navigate to the resource in the Azure Portal.

• Restart Azure VM: Adds a button to restart the Azure VM directly from the workspace overview.

Monitor

• Azure Monitor: Adds a panel to visualize the metrics for the resource.

AI

• Open AI: Adds a button to ask questions or get recommendations using OpenAI based on the workspace data.

The Action Proxy allows you to call other APIs without needing to add the Terrakube frontend to the CORS settings, which is particularly useful if you don't have access to configure CORS. Additionally, it can be used to inject Workspace variables and Global variables into your requests.

Calling the Action Proxy

The proxy supports POST, GET, PUT, and DELETE methods. You can access it using the axiosInstance variable, which contains an Axios object.

To invoke the proxy, use the following URL format: ${context.apiUrl}/proxy/v1

({ context }) => {
   const fetchData = async () => {
    try {
      const response = await axiosInstance.get(`${context.apiUrl}/proxy/v1`, {
        params: {
          targetUrl: 'https://jsonplaceholder.typicode.com/posts/1/comments',
          proxyheaders: JSON.stringify({
            'Content-Type': 'application/json',
          }),
          workspaceId: context.workspace.id
        }
      });

      console.log(response.data);
    } catch (error) {
      console.error('Error fetching data:', error);
    }
 
  };

When calling the Action Proxy, use the following required parameters:

• targetUrl: Contains the URL that you want to invoke.

• proxyHeaders: Contains the headers that you want to send to the target URL.

• workspaceId: The workspace ID that will be used for some validations from the proxy side

Injecting Variables via the Action Proxy

If you need to access sensitive keys or passwords from your API call, you can inject variables using the template notation ${{var.variable_name}}, where variable_name represents a Workspace variable or a Global variable.

Example Usage

const response = await axiosInstance.post(`${context.apiUrl}/proxy/v1`, {
  targetUrl: 'https://api.openai.com/v1/chat/completions',
  proxyHeaders: JSON.stringify({
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ${{var.OPENAI_API_KEY}}'
  }),
  workspaceId: context.workspace.id,
  proxyBody: JSON.stringify({
    model: 'gpt-4',
    messages: updatedMessages,
  })
}, {
  headers: {
    'Content-Type': 'application/json',
  }
});

In this example:

• ${{var.OPENAI_API_KEY}} is a placeholder for a sensitive key that will be injected by the proxy.

• proxyBody contains the data to be sent in the request body.

• proxyHeaders contains the headers to be sent to the target URL.

• targetUrl specifies the API endpoint to be invoked.

• workspaceId is used for validations on the proxy side.

By using the Action Proxy, you can easily interact with external APIs while using Terrakube's capabilities to manage and inject necessary variables securely.

Description

The Resource Details action is designed to show detailed information about a specific resource within the workspace. By using the context of the current state, this action provides a detailed view about the properties and dependencies in a tab within the resource drawer.

Display Criteria

By default this Action is enabled and will appear for all the resources. If you want to display this action only for certain resources, please check filtering actions.

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, you will see a new tab Details with the resource attributes and dependencies.

Description

The Open In Azure Portal action is designed to provide quick access to the Azure portal for a specific resource. By using the context of the current state, this action constructs the appropriate URL and presents it as a clickable button.

Display Criteria

By default, this Action is disabled and when enabled will appear for all the azurerm resources. If you want to display this action only for certain resources, please check display criteria.

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, click the Open in Azure button.

• You will be able to see the Azure portal for that resource.

Description

The Restart VM action is designed to restart a specific virtual machine in Azure. By using the context of the current state, this action fetches an Azure access token and issues a restart command to the specified VM. The action ensures that the VM is restarted successfully and provides feedback on the process.

Display Criteria

By default, this Action is disabled and when enabled will appear for all resources that have resource type azurerm_virtual_machine. If you want to display this action only for certain resources, please check display criteria.

Setup

This action requires the following variables as Workspace Variables or Global Variables in the Workspace Organization:

• ARM_CLIENT_ID: The Azure Client ID used for authentication.

• ARM_CLIENT_SECRET: The Azure Client Secret used for authentication.

• ARM_TENANT_ID: The Azure Tenant ID associated with your subscription.

• ARM_SUBSCRIPTION_ID: The Azure Subscription ID where the VM is located.

Usage

• Navigate to the Workspace Overview or the Visual State and click on a resource name.

• In the Resource Drawer, click the "Restart" button.

• The VM will be restarted, and a success or error message will be displayed.

Description

The Open Documentation action is designed to provide quick access to the Terraform registry documentation for a specific provider and resource type. By using the context of the current state, this action constructs the appropriate URL and presents it as a clickable button.

Display Criteria

By default this Action is enabled and will appear for all the resources. If you want to display this action only for certain resources, please check display criteria.

Usage

• Navigate to the Workspace Overview or the Visual State and click a resource name.

• In the Resource Drawer, Click the Open documentation button

• You will be able to see the documentation for that resource in the Terraform registry

Description

The Azure Monitor Metrics action allows users to fetch and visualize metrics from Azure Monitor for a specified resource.

Display Criteria

By default, this Action is disabled and when enabled will appear for all the azurerm resources. If you want to display this action only for certain resources, please check .

Setup

This action requires the following variables as or in the Workspace Organization:

• ARM_CLIENT_ID: The Azure Client ID used for authentication.

• ARM_CLIENT_SECRET: The Azure Client Secret used for authentication.

• ARM_TENANT_ID: The Azure Tenant ID associated with your subscription.

• ARM_SUBSCRIPTION_ID: The Azure Subscription ID where the VM is located.

Usage

• Navigate to the Workspace Overview or the Visual State and click on a resource name.

• Click the Monitor tab to view metrics for the selected resource.

• You can view additional details for the metrics using the tooltip.

• You can see more details for each chart by navigating through it.

Description

The Ask Workspace action allows users to interact with OpenAI's GPT-4o model to ask questions and get assistance related to their Terraform Workspace. This action provides a chat interface where users can ask questions about their Workspace's Terraform state and receive helpful responses from the AI.

Display Criteria

By default, this Action is disabled and when enabled will appear for all resources. If you want to display this action only for certain resources, please check .

Setup

This action requires the following variables as or in the Workspace Organization:

• OPENAI_API_KEY: The API key to authenticate requests to the OpenAI API. Please check in how to get an OPEN AI api key

Usage

• Navigate to the Workspace and click on the Ask Workspace button.

• Enter your questions and click the Send button or press the Enter key.