Terrakube is an open source collaboration platform for running remote infrastructure as code operations using Terraform or OpenTofu that aims to be a complete replacement for close source tools like Terraform Enterprise, Scalr or Env0.

The platform can be easily installed in any kubernetes cluster, you can easily customize the platform using other open source tools already available for terraform (Example: terratag, infracost, terrascan, etc) and you can integrate the tool with different authentication providers like Azure Active Directory, Google Cloud Identity, Github, Gitlab or any other provider supported by Dex.

Terrakube provides different features like the following:

• Terraform module protocol:

  • This allows Terrakube to expose an open source terraform registry that is protected and is private by default using different Dex for the authentication with different providers.

• Terraform provider protocol:

  • This allows Terrakube to expose an open source terraform registry where you can have create your own private terraform providers or create a mirror of the current terraform providers available in the public Hashicorp registry.

• Handle you infrastructure as code using Organization like closed source tools like Terraform Enterprise and Scalr.

• Easily extended by default integrating with many open source tools available today for terraform CLI.

• Support to run the platform using any RDBMS supported by (mysql, postgres, oracle, sql server, etc).

• Plugins support to extends functionality using different cloud providers and open source tools using the Terrakube Configuration Languague (TCL).

• Easily extends the platform using common technologies like react js, java, spring, elide, liquibase, groovy, bash, go.

• Native integration with the most popular VCS like:

  • Github.

  • Azure DevOps

  • Bitbucket
• Support for SSH key (RSA and ED25519)

• Handle Personal Access Token

• Extends and create custom flows when running terraform remote operations with custom logics like:

  • Approvals

  • Budget reviews

  • Security reviews

Sponsors

This is the high level architecture of the platform

Component descriptions:

• Terrakube API:

  • Expose a JSON:API or GraphQL API providing endpoints to handle:

In a production deployment, it is recommended to host your database backend on external cloud provider like AWS, GCP or Azure.

Using Access Key and Secret

The first step will be to create one s3 bucket with private access

You can handle Terrakube users with differen authentication providers like the following

The easiest way to deploy Terrakube is using our Helm Chart, to learn more about this please review the following:

You can deploy Terrakube using different authentication providers for more information check

Terrakube use two secrets internally to sign the personal access token and one internal token for intercomponent comunnication when using the helm deployment you can change this values using the following keys:

When Terrrakube needs to run behind a corporate proxy the following environment variable can be used in each container:

When using the official helm chart the environment variable setting can be set like the following:

To quickly run terrakube in your test environment please check the following:

To quickly develop Terrakube you can use the following guides:

You can deploy Terrakube to any Kubernetes cluster using the helm chart available in the following repository:

https://github.com/terrakube-io/terrakube-helm-chart

Helm Repository

To use the repository do the following:

helm repo add terrakube-repo https://charts.terrakube.io
helm repo update

The default ingress configuration for terrakube can be customize using a terrakube.yaml like the following:

dex:
  config:
    issuer: http://terrakube-api.minikube.net/dex ## CHANGE THIS DOMAIN
    #.....
    #PUT ALL THE REST OF THE DEX CONFIG AND UPDATE THE URL WITH THE NEW DOMAIN
    #.....

## Ingress properties
ingress:
  useTls: false
  ui:
    enabled: true
    domain: "terrakube-ui.minikube.net" ## CHANGE THIS DOMAIN
    path: "/"
    pathType: "Prefix" 
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/use-regex: "true"
  api:
    enabled: true
    domain: "terrakube-api.minikube.net" ## CHANGE THIS DOMAIN
    path: "/"
    pathType: "Prefix"
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/use-regex: "true"
      nginx.ingress.kubernetes.io/configuration-snippet: "proxy_set_header Authorization $http_authorization;"
  registry:
    enabled: true
    domain: "terrakube-reg.minikube.net" ## Change to your customer domain
    path: "/"
    pathType: "Prefix"
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/use-regex: "true"
      nginx.ingress.kubernetes.io/configuration-snippet: "proxy_set_header Authorization $http_authorization;"
  dex:
    enabled: true
    path: "/dex/"
    pathType: "Prefix"
    annotations:
      kubernetes.io/ingress.class: nginx
      nginx.ingress.kubernetes.io/use-regex: "true"
      nginx.ingress.kubernetes.io/configuration-snippet: "proxy_set_header Authorization $http_authorization;"

Now you can install terrakube using the command

The first step will be to deploy a minio instance inside minikube in the terrakube namespace

Create the file minio-setup.yaml that we can use to create the default user and buckets

Once the minio storage is installed lets get the service name.

The service name for the minio storage should be "miniostorage"

Once minio is installed with a bucket you will need to get the following:

• access key

• secret key

• bucket name

• endpoint (http://miniostorage:9000)

Now you have all the information we will need to create a terrakube.yaml for our terrakube deployment with the following content:

Now you can install terrakube using the command:

To use a PostgreSQL with your Terrakube deployment create a terrakube.yaml file with the following content:

## Terrakube API properties
api:
  defaultDatabase: false
  loadSampleData: false
  properties:
    databaseType: "POSTGRESQL"
    databaseHostname: "server_name.postgres.database.com"
    databaseName: "database_name"
    databaseUser: "database_user"
    databasePassword: "database_password"
    databaseSslMode: "disable"
    databasePort: "5432"

Now you can install terrakube using the command.

Terrakube will support terraform cli custom builds or custom cli mirrors, the only requirement is to expose an endpoint with the following structure:

Example Endpoint:

• https://eov1ys4sxa1bfy9.m.pipedream.net/

{
   "name":"terraform",
   "versions":{
      "1.3.9":{
         "builds":[
            {
               "arch":"amd64",
               "filename":"terraform_1.3.9_linux_amd64.zip",
               "name":"terraform",
               "os":"linux",
               "url":"https://releases.hashicorp.com/terraform/1.3.9/terraform_1.3.9_linux_amd64.zip",
               "version":"1.3.9"
            }
         ],
         "name":"terraform",
         "shasums":"terraform_1.3.9_SHA256SUMS",
         "shasums_signature":"terraform_1.3.9_SHA256SUMS.sig",
         "shasums_signatures":[
            "terraform_1.3.9_SHA256SUMS.72D7468F.sig",
            "terraform_1.3.9_SHA256SUMS.sig"
         ],
         "version":"1.3.9"
      }
   }
}

To support custom terrafom cli releases when using the helm chart us the following:

General security

Terrakube security is based organizations and groups.

An organization can have one or multiple groups and each group have different kind of access to manage the following options:

• Module

  • Manage terraform modules inside an organization

• VCS

Administrator group

There is one special group inside Terrakube called TERRAKUBE_ADMIN, this is the only group that has access to create organizations and grant access to a teams to manage different organization features, you can also customize the group name if you want to use a different name depending on which you are using when running Terrakube.

The first step will be to create one azure storage account with the following containers:

• content

• registry

• tfoutput

• tfstate

Once the storage account is created you will have to get the ""

Now you have all the information we will need to create a terrakube.yaml for our terrakube deployment with the following content:

Now you can install terrakube using the command

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 .

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.

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.

To use a SQL Azure with your Terrakube deployment create a terrakube.yaml file with the following content:

Now you can install terrakube using the command.

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

For example it can be used in the following way:

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

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

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:

Terraform provides a public registry, where you can share and reuse your terraform modules or providers, but sometimes you need to define a Terraform module that can be accessed only within your organization.

Terrakube provides a private registry that works similarly to the and helps you share and privately across your organization. You can use any of the main to maintain your terraform module code.

In this section:

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

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

To use a H2 with your Terrakube deployment create a terrakube.yaml file with the following content:INT

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.

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.

In this section:

Terrakube empowers collaboration between different teams in your organization. To achieve this, you can integrate Terrakube with your version control system (VCS) provider. Although Terrakube can be used with public Git repositories or with private Git repositories using SSH, connecting to your Terraform code through a VCS provider is the preferred method. This allows for a more streamlined and secure workflow, as well as easier management of access control and permissions.

Terrakube supports the following VCS providers:

Webhooks

Terrakube uses webhooks to monitor new commits. This features is not available in SSH and Azure DevOps.

• When new commits are added to a branch, Terrakube workspaces based on that branch will automatically initiate a Terraform job. Terrakube will use the "Plan and apply" template by default, but you can specify a different Template during the Workspace creation.

• When you specify a directory in the Workspace. Terrakube will run the job only if a file changes in that directory

In progress

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:

Terrakube can use SSH keys to authenticate to your private repositories. The SSH keys can be uploaded inside the settings menu.

To handle SSH keys inside Terrakube your team should have "Manage VCS settings" access

Terrakube support keys with RSA and ED25519

SSH keys can be used to authenticate to private repositories where you can store modules or workspaces

Once SSH keys are added inside your organization you can use them like the following example:

Modules:

Workspace:

SSH Key Injection

The selected SSH key will be used to clone the workspace information at runtime when running the job inside Terrakube, but it will also be injected to the job execution to be use inside our terraform code.

For example if you are using a module using a GIT connection like the following:

When running the job, internally terraform will be using the selected SSH key to clone the necesary module dependencies like the below image:

When using a VCS connection you can select which SSH key should be injected when downloading modules in the workspace settings:

This will allow to use modules using the git format inside a workspace with VCS connection like the following:

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

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 or a.

Example Usage

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.

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

The docker images are generated using cloud native buildpacks with the maven plugin, more information can be found in these links:

Alpaquita Linux (Experimental)

From Terrakube 2.17.0 we generate 3 additional docker images for the API, Registry and Executor components that are based on that are designed and optimized for Spring Boot applications.

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 .

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.

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.

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

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:

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

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

Contains the Terrakube api Url. Useful if you want to use the or execute a call to the Terrakube API.

Available for action types

• workspace/action

• workspace/resourcedrawer/action

• workspace/resourcedrawer/tab

Requirements

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

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

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

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

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"

Local Domains

We will be using following domains to run Terrakube with docker compose:

HTTPS Local Certificates

Install mkcert to generate the local certificates.

Generate local CA certificate

Create Docker Network

We will be using 10.25.25.253 for our the traefik gateway

Local DNS entries

Update the /etc/hosts file adding the following entries:

Running Terrakube Locally with HTTPS

After 1 or 2 minutes Terrakube will be available in the following URL once all the container are initialized correctly:

• • Username:

  • Password: admin

Special thanks to who has created the setup example to use Terrakube

Original Reference:

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.

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.

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

Terraform Plan/Destroy Cli Templates

Will be used when you execute terraform destroyusing the terraform cli

The component use to execute terraform/opentofu configuration is stateless so everytime that it is executing a job will try to download the terraform/opentofu providers, in order to speed up the execution the following environment variable can be added to have a provider cache.

TF_PLUGIN_CACHE_DIR=/home/cnb/.terraform.d/plugin-cache

When deploying the helm chart the following can be used to add an emptyDir volume to cache the providers.

executor:
  volumes:
    - name: cache-volume
      emptyDir:
        sizeLimit: 1024Mi
  volumeMounts:
  - mountPath: /home/cnb/.terraform.d/plugin-cache
    name: cache-volume

When running tofu init, temporary files such as .terraform.lock.hcl are generated based on the current machine’s architecture. On subsequent runs, OpenTofu verifies that the required providers match the architecture specified in the lock file to decide whether a new download is necessary.

However, when working locally on macOS, the architecture (e.g., darwin/amd64 or darwin/arm64) differs from the architecture used by remote Terrakube jobs (linux/arm64). This mismatch forces OpenTofu to redownload providers each time.

If you want to avoid that issue you need to run this command to generate lock file for Terrakube's image architecture.

tofu providers lock -platform=linux_amd64

Click Registry in the main menu and then click the Publish module button

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.

In the next screen, configure the required fields and click the Publish Module button.

The module will be published inside the specified organization. On the details page, you can view available versions, read documentation, and copy a usage example.

Releasing New Versions of a Module

To release a new version of a module, create a new release tag to its VCS repository. The registry automatically imports the new version.

Deleting Modules

In the Module details page click the Delete Module button and then click the Yes button to confirm

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

By default the helm chart is using bitnami redis, this container is only for testing purposes and for a real cluster it is better to use an external redis.

To enable it, the following values can be used:

api:
  defaultRedis: false
  env:
  - name: TerrakubeRedisSSL
    value: "true"
  - name: TerrakubeRedisTruststorePath
    value: /layers/paketo-buildpacks_bellsoft-liberica/jre/lib/security/cacerts 
  - name: TerrakubeRedisTruststorePassword
    value: changeit
  properties:
    redisHostname: "MY-REDIS-IN-AZURE.redis.cache.windows.net"
    redisPassword: "MY-REDIS-ACCESS-KEY"
    redisPort: "6380"

executor:
  env:
  - name: SERVICE_BINDING_ROOT
    value: /mnt/platform/bindings
  - name: TerrakubeRedisSSL
    value: "true"
  - name: TerrakubeRedisTruststorePath
    value: /layers/paketo-buildpacks_bellsoft-liberica/jre/lib/security/cacerts 
  - name: TerrakubeRedisTruststorePassword
    value: changeit

Ephemeral Executor with Redis SSL

To add the additional environment variables to the ephemeral executor the following could be used:

Value:

For using repositories from Gitlab.com with Terrakube workspaces and modules you will need to follow these steps:

Navigate to the desired organization and click the Settings button, then on the left menu select VCS Providers

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

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

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

Example before template import:

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

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

The sample template can be found .

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

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.

The first step will be to create one google storage bucket with private access

Terrakube allow to have one or multiple agents to run jobs, you can have as many agents as you want for a single organization.

To use this feature you could deploy a single executor component using the following values:

Requirements

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

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.

To use Terrakube’s VCS features with a self-hosted GitLab Enterprise Edition (EE) or GitLab Community Edition (CE), follow these instructions. For GitLab.com, see the separate instructions.

• Got to the organization settings you want to configure. Select the VCS Providers on the left menu and click the Add VCS provider button on the top right corner.

• Click the Gitlab button and then click the GitLab Enterprise option.

• On the next screen, enter the following information about your GitLab instance:

• Use a different browser tab to access your GitLab instance and sign in with the account that you want Terrakube to use. You should use a service user account for your organization, but you can also use a personal account.

• Navigate to GitLab "User Settings > Applications" page. This page is located at https://<GITLAB INSTANCE HOSTNAME>/profile/applications

• In the GitLab page, complete the required fields and click Save application

• On the next screen, copy the Application ID and Secret

• Go back to Terrakube to enter the information you copied from the previous step. Then, click the Connect and Continue button.

You will be redirected to GitLab. Click the Authorize button to complete the connection.

Finally, if the connection was established successfully, you will be redirected to the VCS provider’s page in your organization. You should see the connection status with the date and the user that created the connection.

And now, you will be able to use the connection in your workspaces and modules:

Terrakube can be installed in minikube as a sandbox environment to test, to use it please follow this:

Setup Helm Repository

Setup Minikube

Setup Terrakube namespace

Setup DNS records

Install Terrakube

The environment has some users, groups and sample data so you can test it quickly.

Visit http://terrakube-ui.minikube.net and login using [email protected] with password admin

You can login using the following user and passwords

Select the "simple" organization and the "sample_simple" workspace and run a job.

For using repositories from GitHub.com with Terrakube workspaces and modules you will need to follow these steps:

Navigate to the desired organization and click the Settings button, then on the left menu select VCS Providers

Click the Github button and then click the Github Cloud option.

In the next screen click the link to in Github

In the Github page, complete the required fields and click Register application

Next, generate a new client secret

Copy the Client Id and Client Secret from Github and go back to Terrakube to complete the required information. Then, click the Connect and Continue button

You will see the Github page, click the Authorize button to complete the connection

Finally, if the connection was established successfully, you will be redirected to the VCS provider’s page in your organization. You should see the connection status with the date and the user that created the connection.

And now, you will be able to use the connection in your workspaces and modules:

Terrakube components support Open Telemetry by default to enable effective observability.

To enable telemetry inside the Terrakube components please add the following environment variable:

Once the open telemetry agent is enable we can use other environment variables to setup the monitoring for our application for example to enable jaeger we could add the following using addtional environment variables:

Now we can go the jaeger ui to see if everything is working as expected.

There are several differente configuration options for example:

Jaeger exporter

The exporter. This exporter uses gRPC for its communications protocol.

Zipkin exporter

The exporter. It sends JSON in to a specified HTTP URL.

Prometheus exporter

The exporter.

Open Telemetry Example

One small example to show how to use open telemetry with docker compose can be found in the following URL:

For using repositories from Azure Devops with Terrakube workspaces and modules you will need to follow these steps:

Navigate to the desired organization and click the Settings button, then on the left menu select VCS Providers

Click the Azure Devops button

In the next screen click the link to in Azure Devops

In the Azure Devops page, complete the required fields and click Create application

In the next screen, copy the App ID and Client Secret

Go back to Terrakube to enter the information you copied from the previous step. Then, click the Connect and Continue button.

You will see an Azure Devops window, click the Accept button to complete the connection

Finally, if the connection was established successfully, you will be redirected to the VCS provider’s page in your organization. You should see the connection status with the date and the user that created the connection.

And now, you will be able to use the connection in your workspaces and modules:

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

For using repositories from GitHub.com with Terrakube workspaces and modules you will need to follow these steps:

Navigate to the desired organization and click the Settings button, then on the left menu select VCS Providers

Select the option for Github App

In the next page click to create a new application adding the required information

Complete the information like the following:

Disable webhook option.

Grant the require repository, organization or account permissions and in which type of account you will do the installation.

Add "Contents" with "Read-Only"

Add "Webhooks" with "Read and Write"

Add "Commit statuses" to "Read and write"

Finally click "Create Github App"

After creating the application you need to copy the APP Id to the Terrakube UI

Scroll down and search for "Generate Private Key" and generate a new private key.

After downloading the private key we need to to transform the key to PKCS8 using the following command:

Now we can add the private key in the Terrakube UI.

The github app will be added to Terrakube and will be shown like this:

The final step will be to install the application to your Github account like this.

And select which repositories will be used with terrakube

The installation should look like this

Now to use the Github Application when creating a new workspace we just need to add our new connection.

To use Terrakube’s VCS features with a self-hosted GitHub Enterprise, follow these instructions. For GitHub.com, see the separate instructions.

• Got to the organization settings you want to configure. Select the VCS Providers on the left menu and click the Add VCS provider button on the top right corner..

• Click the Github button and then click the Github Enterprise option.

• On the next screen, enter the following information about your Github Enterprise instance:

• Use a different browser tab to access your GitHub Enterprise instance and sign in with the account that you want Terrakube to use. You should use a service user account for your organization, but you can also use a personal account.

• Navigate to GitHub's Register a New OAuth Application page. This page is located at https://<GITHUB INSTANCE HOSTNAME>/settings/applications/new

• In the Github Enterprise page, complete the required fields and click Register application

Next, generate a new client secret

Copy the Client Id and Client Secret from Github Enterprise and go back to Terrakube to complete the required information. Then, click the Connect and Continue button

You will be redirected to Github Enterprise. Click the Authorize button to complete the connection.

When the connection is successful, you will go back to the VCS provider’s page in your organization. You will see the connection status, the date, and the user who made the connection.

You can now use the connection for your workspaces and modules.

This page contains the configuration for a development container that provides a consistent environment for working with Terrakube.

The devcontainer includes all the necessary tools and dependencies to develop both the Java backend, TypeScript frontend components and includes terraform CLI.

Make sure The below was tested using Ubuntu-based distribution, not sure if this will work with macos, windows or codespaces

Features

• Java 17 (Liberica)

• Maven 3.9.9

• Node.js 20.x with Yarn

• VS Code extensions for Java, JavaScript/TypeScript

Getting Started

Prerequisites

Local Development Domains

To use the devcontainer we need to setup the following domains in our local computer:

HTTPS Local Certificates

Install to generate the local certificates.

To generate local CA certificate execute the following:

Create Docker Network for the devcontainer

We will be using 10.25.25.253 for our the traefik gateway

Local DNS entries

Update the /etc/hosts file adding the following entries:

Opening the Project in a Dev Container

• Clone the Terrakube repository and run the project:

1. When prompted to "Reopen in Container", click "Reopen in Container". Alternatively, you can:

   • Press F1 or Ctrl+Shift+P

   • Type "Remote-Containers: Reopen in Container" and press Enter

2. Wait for the container to build and start. This may take a few minutes the first time.

Ports

The devcontainer forwards the following ports:

• 8080: Terrakube API

• 8075: Terrakube Registry

• 8090: Terrakube Executor

• 3000: Terrakube UI

Customization

You can customize the devcontainer by modifying:

• .devcontainer/devcontainer.json: VS Code settings and extensions

• .devcontainer/Dockerfile: Container image configuration

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

Requirements

• A working Keycloak server with a configured realm.

Steps for configuring Terrakube with Keycloak

For configuring Terrakube with Keycloak using Dex the following steps are involved:

• Keycloak client creation and configuration for Terrakube.

• Configure Terrakube so it works with Keycloak.

• Testing the configuration.

Keycloak client creation

Log in to Keycloak with admin credentials and select Configure > Clients > Create. Define the ID as TerrakubeClient and select openid-connect as its protocol. For Root URL use Terrakube's GUI URL. Then click Save.

A form for finishing the Terrakube client configuration will be displayed. These are the fields that must be fulfilled:

• Name: in this example it has the value of TerrakubeClient.

• Client Protocol: it must be set to openid-connect.

• Access Type: set it to confidential.

Then click Save.

Notice that, since we set Access Type to confidential, we have an extra tab titled Credentials. Click the Credentials tab and copy the Secret value. It will be used later when we configure the Terrakube's connector.

Depending on your configuration, Terrakube might expect different client scopes, such as openid, profile, email, groups, etc. You can see if they are assigned to TerrakubeClient by clicking on the Client Scopes tab (in TerrakubeClient).

If they are not assigned, you can assign them by selecting the scopes and clicking on the Add selected button.

If some scope does not exist, you must create it before assigning it to the client. You do this by clicking on Client Scopes, then click on the Create button. This will lead you to a form where you can create the new scope. Then, you can assign it to the client.

Terrakube configuration

We have to configure a Dex connector to use with Keycloak. Add a new connector in Dex's configuration, so it looks like this:

This is the simpler configuration that we can use. Let's see some notes about this fields:

• type: must be oidc (OpenID Connect).

• name: this is the string shown in the connectors list in Terrakube GUI.

• issuer: it refers to the Keycloak server. It has the form [http|https]://<KEYCLOAK_SERVER>/realms/<REALM_NAME>

{% hint style="info" %} If your users do not have a name set (First Name field in Keycloak), you must tell oidc which attribute to use as the user's name. You can do this giving the userNameKey:

{% endhint %}

Testing Terrakube authentication

When we click on Terrakube's login button we are given the choice to select the connector we want to use:

Click on Log in with TerrakubeClient. You will be redirected to a login form in Keycloak:

After login, you are redirected back to Terrakube and a dialog asking you to grant access is shown

Click on Grant Access. That is the last step. If everything went right, now you should be logged in Terrakube.

Dex can be further configured by setting dex.config.web.skipApprovalScreen to avoid granting access everytime. It is also recommended to switch to a database mode instead of memory to avoid forcing all users to re-authenticate each time dex pod crashes. Switching to database mode will also allow you to run several dex pods for better availability.

All users in an organization with Manage Modules permission can view the Terrakube private registry and use the available providers and modules.

Using private modules

Click Registry in the main menu. And then click the module you want to use.

In the module page, select the version in the dropdown list

You can copy the code reference from the module page

For example:

Submodules

If your repository has submodules, Terrakube will scan the modules folder to identify all the submodules. Then, you will see a dropdown list with the submodules in the UI.

To view the readme file, inputs, outputs, resources and other information for any submodule, you can choose the submodule you want.

You can also copy the details of how to configure any submodule, just like the main module. Example:

In the submodule view you can switch to the differents submodules.

Or you can back to the main module with the Back button on the top of the page.

Configure Authentication

When running Terraform on the CLI, you must configure credentials in to access the private modules.

For example:

To get the API token you can check .

As an alternative you can run the command to obtain and save an user API token.

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.

Requirementes

The dynamic provider credential setup in OpenBao/Vault can be found inside the following link:

The following will explain how to run the executor component in"ephemeral" mode.

These environment variables can be used to customize the API component:

• ExecutorEphemeralNamespace (Default value: "terrakube")

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.

For using repositories from Bitbucket.com with Terrakube workspaces and modules you will need to follow these steps:

Navigate to the desired organization and click the Settings button, then on the left menu select VCS Providers

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