1 of 35

Terrakube CLI

The CLI is not compatible with Terrakube 2.X, it needs to be updated and there is an open issue for this feature

terrakube cli is Terrakube on the command line. It brings organizations, workspaces and other Terrakube concepts to the terminal.

In this section:

Getting started

terrakube cli is Terrakube on the command line. It brings organizations, workspaces and other Terrakube concepts to the terminal.

Installation

You can find installation instructions here

Getting help

When you are working with terrakube cli probably you will need some help with the supported commands and flags and you can use for that, however a better option is to use the same cli to get help using --help flag or -h shortand. The embedded help provides you more detail for each command and some examples you can use as reference

Authentication

You will receive a code, open the url in a web browser and provide your account details. See below code as reference

Create your Organization

Organizations are privately shared spaces for teams to collaborate on infrastructure.

If you don't have an organization created yet, you can create a new one.

The result for the above command should be something like this

Working with Teams

Once you create your organization you will probably want to define the teams and permissions for the organization, so you can use the team command for that.

Create a Workspace

After having given permissions to our teams we can create a workspace.

And define some variables for the created workspace

If you want to avoid entering the organization or the workspace in each command you can use environment variables, so the previous commands would be simplified as follows.

Run a Job

Now that you have a workspace with all the variables defined, you can execute a job, basically a job is a remote terraform apply, plan or destroy. So if you want to run apply we can execute the following command.

After a few minutes the job will finish and you can check the result

You can use a curl command to retrieve the log result from the terminal

Defining your Modules

Usually you will want to define your infrastructure templates as code using terraform and for this you can use the modules so others can reuse them.

Simplifying the commands

In order to simplify the commands when you are working with the cli, you can use shortands and alias and some environment variables. See the following sections for more details.

Use the --help flag to get the details about available shorthands and alias for each command

Using shorthands

Using alias

Using environment variables

Installation

MacOs

terrakube is available via Homebrew and as a downloadable binary from the releases page.

brew install azbuilder/cli/terrakube

Windows

terrakube is available via Chocolatey and as a downloadable binary from the releases page.

choco install terrakube

Commands

Usage

terrakube [command]

Commands

Click on each command to see more details

Command

Description

terrakube login

Authenticate with a Terrakube Server

Usage

terrakube login [flags]

Flags

  -c, --client-id string   Azure application Client id (required)
  -h, --help               help for login
  -p, --path string        Terrakube Server path
      --scheme string      Terrakube Server scheme: http or https (default "http")
  -s, --server string      Terrakube Server url (required)
  -t, --tenant-id string   Azure tenant Id (required)

Examples

terrakube login -s localhost:8080 -c 853b26d6-1849-4c00-8543-da5805b0e593 -t 0e6427af-ab9e-4af6-9f6f-bc098f470d75

terrakube logout

Logout from a Terrakube Server

Usage

terrakube logout [flags]

terrakube organization

This command consists of multiple subcommands to interact with organizations. It can be used to create, update, delete and list organizations.

Usage

Commands

Command

Description

Aliases

organization
org

Description

Aliases

organization
org

team list

terrakube team list

List teams

Usage

terrakube team list [flags]

Flags

  -f, --filter string            Filter
  -h, --help                     help for list
      --organization-id string   Organization Id (required)

Examples

List all existing teams in an organization

terrakube team list --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb

team create

Create a Team

Usage

 terrakube team create [flags]

Flags

  -h, --help                     help for create
      --manage-module            Manage Module Permissions
      --manage-provider          Manage Provider Permissions
      --manage-workspace         Manage Workspaces Permissions
  -n, --name string              Name of the new Team (required)
      --organization-id string   Organization Id (required)

Examples

Create a new team

 terrakube team create --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb -n AZB_USER --manage-workspace=true --manage-module=true --manage-provider=true

team update

Usage

 terrakube team update [flags]

Flags

  -h, --help                     help for update
      --id string                Id of the Team (required)
      --manage-module            Manage Module Permissions
      --manage-provider          Manage Provider Permissions
      --manage-workspace         Manage Workspaces Permissions
  -n, --name string              Name of the Team
      --organization-id string   Organization Id (required)

Examples

Update the permissions for a Team

terrakube team update --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb --id 38b6635a-d38e-46f2-a95e-d00a416de4fd --manage-workspace=true --manage-module=false --manage-provider=true

team delete

Delete a team

Usage

terrakube team delete [flags]

Flags

  -h, --help                     help for delete
      --id string                Id of the Team (required)
      --organization-id string   Organization Id (required)

Examples

Delete a team

 terrakube team delete --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb --id 38b6635a-d38e-46f2-a95e-d00a416de4fd

terrakube workspace

This command consists of multiple subcommands to interact with workspaces. It can be used to create, update, delete and list workspaces.

Usage

terrakube workspace [command]

Commands

Command

Description

Aliases

workspace
wrk

workspace list

List workspaces

Usage

terrakube workspace list [flags]

Flags

  -f, --filter string            Filter
  -h, --help                     help for list
      --organization-id string   Organization Id (required)

Examples

List all existing workspaces in an Organization

terrakube workspace list --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb

workspace create

Create a workspace

Usage

 terrakube workspace create [flags]

Flags

  -b, --branch string              Branch of the new workspace
  -h, --help                       help for create
  -n, --name string                Name of the new workspace (required)
      --organization-id string     Id of the organization (required)
  -s, --source string              Source of the new workspace
  -t, --terraform-version string   Terraform Version use in the new workspace

Examples

Create a new workspace

terrakube workspace create --organization-id 312b4415-806b-47a9-9452-b71f0753136e -n myWorkspace -s https://github.com/AzBuilder/terraform-sample-repository.git -b master -t 0.15.0

workspace update

Update a workspace

Usage

 terrakube workspace update [flags]

Flags

  -b, --branch string              Branch of the workspace
  -h, --help                       help for update
      --id string                  Id of the workspace (required)
  -n, --name string                Name of the workspace (required)
      --organization-id string     Id of the organization (required)
  -s, --source string              Source of the workspace
  -t, --terraform-version string   Terraform Version use in the workspace

Examples

Update Terraform version in workspace

terrakube workspace update --organization-id 312b4415-806b-47a9-9452-b71f0753136e --id 38b6635a-d38e-46f2-a95e-d00a416de4fd -t 0.14.0

workspace delete

Delete a workspace

Usage

 terrakube workspace delete [flags]

Flags

  -h, --help                     help for delete
      --id string                Id of the workspace (required)
      --organization-id string   Organization Id (required)

Examples

Delete a workspace

terrakube workspace delete --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb --id 38b6635a-d38e-46f2-a95e-d00a416de4fd

workspace variable

This command consists of multiple subcommands to interact with variables. It can be used to create, update, delete and list variables.

Usage

terrakube workspace variable [command]

Commands

Command

Description

Aliases

variable
var

variable list

List variables

Usage

terrakube workspace variable list [flags]

Flags

  -f, --filter string            Filter
  -h, --help                     help for list
      --organization-id string   Organization Id (required)
  -w, --workspace-id string      Workspace Id (required)

Examples

List all existing variables for a workspace

terrakube workspace variable list --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb -w 38b6635a-d38e-46f2-a95e-d00a416de4fd

terrakube variable

variable update

Update a variable

Usage

terrakube workspace variable update [flags]

Flags

  -c, --category string          Category of the variable. Valid values are TERRAFORM or ENV
  -d, --description string       Description of the variable
      --hcl                      Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
  -h, --help                     help for update
      --id string                Id of the variable (required)
  -k, --key string               Key of the variable
      --organization-id string   Organization Id (required)
  -s, --sensitive                Whether the value is sensitive. If true then the variable is written once and not visible thereafter.
  -v, --value string             Value of the variable
  -w, --workspace-id string      Workspace Id (required)

Examples

Update the value of the variable

terrakube workspace variable update --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb -w 38b6635a-d38e-46f2-a95e-d00a416de4fd --id 38b6635a-d38e-46f2-a95e-d00a416de4fd -v "new value"

variable delete

Delete a variable

Usage

terrakube workspace variable delete [flags]

Flags

  -h, --help                     help for delete
      --id string                Id of the variable (required)
      --organization-id string   Organization Id (required)
  -w, --workspace-id string      Workspace Id (required)

Examples

Delete a variable

terrakube workspace variable delete --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb  -w 38b6635a-d38e-46f2-a95e-d00a416de4fd --id 38b6635a-d38e-46f2-a95e-d00a416de4fd

variable create

Create a variable

Usage

terrakube workspace variable create [flags]

Flags

  -c, --category string          Category of the new variable. Valid values are TERRAFORM or ENV
  -d, --description string       Description of the new variable
      --hcl                      Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables.
  -h, --help                     help for create
  -k, --key string               Key of the new variable (required)
      --organization-id string   Organization Id (required)
  -s, --sensitive                Whether the value is sensitive. If true then the variable is written once and not visible thereafter.
  -v, --value string             Value for the new variable
  -w, --workspace-id string      Workspace Id (required)

Create a new variable

terrakube workspace variable create --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb -w 38b6635a-d38e-46f2-a95e-d00a416de4fd -k tag_name -v "Hola mundo" --hcl=false --sensitive=false --category TERRAFORM

terrakube job

This command consists of multiple subcommands to interact with jobs. It can be used to create and list teams.

Usage

terrakube job [command]

Commands

Command

Description

job list

List jobs

Usage

terrakube job list [flags]

Flags

  -f, --filter string            Filter
  -h, --help                     help for list
      --organization-id string   Organization Id (required)

Examples

List all existing jobs in an Organization

terrakube job list --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb

job create

Create a job

Usage

Flags

Examples

Create a new job

terrakube module

This command consists of multiple subcommands to interact with modules. It can be used to create, update, delete and list modules.

Usage

terrakube module [command]

Commands

Command

Description

Aliases

module
mod

module list

List Modules

Usage

terrakube module list [flags]

Flags

  -f, --filter string            Filter
  -h, --help                     help for list
      --organization-id string   Organization Id (required)

Examples

List all existing modules in an Organization

terrakube module list --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb

module create

Create a module

Usage

 terrakube module create [flags]

Flags

  -d, --description string       Description of the new module
  -h, --help                     help for create
  -n, --name string              Name of the new module (required)
      --organization-id string   Organization Id (required)
  -p, --provider string          Provider of the new module
  -s, --source string            Source of the new module

Examples

Create a new module

terrakube module create --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb -n myModule -d "module description" -p azurerm -s https://github.com/AzBuilder/terraform-sample-repository.git

module update

Update a module

Usage

 terrakube module update [flags]

Flags

  -d, --description string       Description of the module
  -h, --help                     help for update
      --id string                Id of the module (required)
  -n, --name string              Name of the module
      --organization-id string   Organization Id (required)
  -p, --provider string          Provider of the module
  -s, --source string            Source of the module

Update the description of the module

terrakube module update --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb --id 38b6635a-d38e-46f2-a95e-d00a416de4fd -d "new description"

module delete

Delete a module

Usage

 terrakube module delete [flags]

Flags

  -h, --help                     help for delete
      --id string                Id of the module (required)
      --organization-id string   Organization Id (required)

Examples

Delete a module

terrakube module delete --organization-id e5ad0642-f9b3-48b3-9bf4-35997febe1fb --id 38b6635a-d38e-46f2-a95e-d00a416de4fd

Getting started

terrakube cli is Terrakube on the command line. It brings organizations, workspaces and other Terrakube concepts to the terminal.

Installation

You can find installation instructions here

Getting help

Authentication

Run to authenticate with your account. But first you need to set some environment variables.

You can also pass this values using however is recommended to use environment variables in the case you need to authenticate several times or if you are running an automatic script.

Open your terminal and execute the following commands in order to setup your terrakube environment and get authenticated. You can get the server, path, scheme, tenant id and client id values during the

export TERRAKUBE_SERVER="my-terrakube.com"
export TERRAKUBE_PATH="terrakube"
export TERRAKUBE_SCHEME="https"
export TERRAKUBE_TENANT_ID="59a1b348-548d-4360-b2e2-9d2b849527a8"
export TERRAKUBE_CLIENT_ID="7a307a36-e08b-4954-a9fb-03a67e082fc4"

terrakube login

You will receive a code, open the url in a web browser and provide your account details. See below code as reference

To sign in, use a web browser to open the page 
https://microsoft.com/devicelogin and enter the code AAM4MVU96 to authenticate.

Create your Organization

Organizations are privately shared spaces for teams to collaborate on infrastructure.

You can check the organizations you have access using

terrakube organization list

If you don't have an organization created yet, you can create a new one.

terrakube organization create --name MyOrganization --description "Getting started Organization"

The result for the above command should be something like this

{
    "attributes": {
        "description": "Getting started Organization",
        "name": "MyOrganization"
    },
    "id": "8a6e9998-165c-49f0-953c-d3fb0924731a",
    "relationships": {
        "job": {},
        "module": {},
        "workspace": {}
    },
    "type": "organization"
}

For more commands and options in organization see the full documentation for

Working with Teams

Once you create your organization you will probably want to define the teams and permissions for the organization, so you can use the team command for that.

terrakube team create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name AZB_USER --manage-workspace=true --manage-module=true --manage-provider=true

In the previous command we are creating a new team inside our new Organization and for this case we are providing permissions to manage workspaces, modules and providers. In the name flag we are using an Azure AD Group, so all the team members are defined inside the AD group. For more details about teams and permissions you can see .

Create a Workspace

After having given permissions to our teams we can create a workspace.

terrakube workspace create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name MyWorkspace --source https://github.com/AzBuilder/terraform-sample-repository.git --branch master --terraform-version 0.15.0

And define some variables for the created workspace

terrakube workspace variable create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --workspace-id 38b6635a-d38e-46f2-a95e-d00a416de4fd --key tag_name --value "Hola mundo" --hcl=false --sensitive=false --category TERRAFORM

If you want to avoid entering the organization or the workspace in each command you can use environment variables, so the previous commands would be simplified as follows.

export TERRAKUBE_ORGANIZATION_ID=8a6e9998-165c-49f0-953c-d3fb0924731a
terrakube workspace create --name MyWorkspace --source https://github.com/AzBuilder/terraform-sample-repository.git --branch master --terraform-version 0.15.0
export TERRAKUBE_WORKSPACE_ID=38b6635a-d38e-46f2-a95e-d00a416de4fd
terrakube workspace variable create --key tag_name --value "Hola mundo" --hcl=false --sensitive=false --category TERRAFORM

Run a Job

terrakube job create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --workspace-id 38b6635a-d38e-46f2-a95e-d00a416de4fd  --command apply

After a few minutes the job will finish and you can check the result

terrakube job list --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a

You can use a curl command to retrieve the log result from the terminal

Defining your Modules

Usually you will want to define your infrastructure templates as code using terraform and for this you can use the modules so others can reuse them.

terrakube module create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name myModule --description "module description" --provider azurerm --source https://github.com/AzBuilder/terraform-sample-repository.git

Simplifying the commands

In order to simplify the commands when you are working with the cli, you can use shortands and alias and some environment variables. See the following sections for more details.

Use the --help flag to get the details about available shorthands and alias for each command

Using shorthands

# without shorthand
terrakube organization create --name MyOrganization --description "Getting started Organization" 

# using shorthand
terrakube organization create -n MyOrganization -d "Getting started Organization"

Using alias

# without alias
terrakube organization create --name MyOrganization --description "Getting started Organization"

# using alias and shorthand
terrakube org create -n MyOrganization -d "Getting started Organization"

Using environment variables

# creating multiple modules without env variables
terrakube module create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name myModule --description "module description" --provider azurerm --source https://github.com/AzBuilder/terraform-sample-repository.git 
terrakube module create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name myModule2 --description "module description 2" --provider azurerm --source https://github.com/AzBuilder/terraform-sample-repository.git
terrakube module create --organization-id 8a6e9998-165c-49f0-953c-d3fb0924731a --name myModule3 --description "module description 3" --provider azurerm --source https://github.com/AzBuilder/terraform-sample-repository.git

# creating multiple modules using shorthand, alias and env variables
export TERRAKUBE_ORGANIZATION_ID=8a6e9998-165c-49f0-953c-d3fb0924731a
terrakube mod create -n myModule -d "module description" -p azurerm -s https://github.com/AzBuilder/terraform-sample-repository.git 
terrakube mod create -n myModule2 -d "module description 2" -p azurerm -s https://github.com/AzBuilder/terraform-sample-repository.git
terrakube mod create -n myModule3 -d "module description 3" -p azurerm -s https://github.com/AzBuilder/terraform-sample-repository.git