Terrakube Documentation

Terrakube is an open-source IaC (Infrastructure as Code) Automation and Collaboration software. Key capabilities include:

• Private Registry: Host and publish Terraform Modules and Providers privately.
• Organizations and Workspaces: Structured management of infrastructure using Organizations and Workspaces. Workspaces support Tags for grouping, organizing, and filtering.
• Version Control Integration: Connects with GitHub (Cloud and Enterprise), GitLab (EE and CE), Bitbucket, and Azure DevOps to manage Terraform/OpenTofu code.
• Terraform Workflow: Execute terraform apply, terraform plan, and terraform destroy from anywhere. Includes management of variables and Terraform state files.
• Custom Workflows: Extend IaC workflows using tools like OPA or Infracost via Terrakube extensions or the Terrakube API (e.g., for compliance, cost estimation, or security scans).
• Access Control: Integrates with Dex to support identity providers like Azure Active Directory, Amazon Cognito, GitHub, and SAML. Supports granular permissions for Workspaces, Modules, and VCS using existing groups.
• Remote Backend: Supports both remote backend and cloud blocks, allowing workflows to be run directly from the Terraform/OpenTofu CLI.

Terrakube supports Attribute-Based Access Control (ABAC) by passing session tags during the AWS AssumeRoleWithWebIdentity call. This allows a single IAM role to serve multiple workspaces by scoping permissions based on the workspace name.

Enabling Session Tags

Session tags are opt-in. To enable them, you must set the following environment variable in your Terrakube workspace:

• ENABLE_AWS_SESSION_TAGS=true

Warning: Enabling this requires the sts:TagSession permission in your IAM role's trust policy. If this permission is missing, the identity assumption will fail.

Available Transitive Principal Tags

When enabled, Terrakube sends the following tags:

• terrakube:org: The organization name.
• terrakube:workspace: The workspace name.
• terrakube:project: The project name (only if the workspace belongs to a project).

IAM Trust Policy Requirements

To use session tags, your IAM Role Trust Policy must:

1. Allow the sts:TagSession action.
2. Use a ForAllValues:StringEquals condition on aws:TagKeys to restrict which tags Terrakube can pass. This prevents unauthorized tag injection.

Example Trust Policy snippet:

"Action": [
  "sts:AssumeRoleWithWebIdentity",
  "sts:TagSession"
],
"Condition": {
  "StringEquals": {
    "terrakube-api.mydomain.com:aud": "aws.workload.identity"
  },
  "StringLike": {
    "terrakube-api.mydomain.com:sub": "organization:my-org:workspace:*"
  },
  "ForAllValues:StringEquals": {
    "aws:TagKeys": [
      "terrakube:org",
      "terrakube:workspace",
      "terrakube:project"
    ]
  }
}

By default, Terrakube uses inbound service hooks to trigger runs when code changes. When a workspace is saved, Terrakube automatically creates an Azure DevOps service hook subscription that posts to the Terrakube webhook endpoint.

Requirements

• Network: The Terrakube webhook endpoint must be reachable from the public internet (since hooks are delivered from Azure DevOps cloud).
• Permissions: The service principal or token used must have Edit Subscriptions permission to create the hooks.

Supported Events

Each delivery is authenticated using a per-webhook x-terrakube-token header. Terrakube reports commit status back to Azure DevOps as the run progresses.

Use these commands to set up a development environment with OpenBao, including enabling auth methods (userpass, approle, jwt), setting up KV secrets, and applying the Terrakube policy and JWT role.

# Start OpenBao in dev mode
bao server -dev -dev-root-token-id="dev-only-token" 

# Setup configuration
export VAULT_ADDR='http://localhost:8200'
bao login dev-only-token
bao auth enable userpass
bao write auth/userpass/users/terrakube password=p@ssw0rd
bao auth enable approle
bao write auth/approle/role/terrakube-role secret_id_ttl=10m token_ttl=20m token_max_ttl=30m
bao secrets enable -path shared -version 2 kv
bao kv put -mount shared kv/creds username=terrakube password=p@ssw0rd
bao auth enable jwt
bao write auth/jwt/config oidc_discovery_url="https://terrakube-api.platform.local" bound_issuer="https://terrakube-api.platform.local" 
bao policy write tfc-policy terrakube-policy.hcl
bao write auth/jwt/role/tfc-role @vault-jwt-auth-role.json

Before compiling or running the Terrakube UI, you must define several environment variables on your local machine. These variables are used to configure the connection to the Terrakube API, Dex authentication, and registry settings.

To simplify this, run the ./setupEnv.sh script to generate a .env file in your local directory. The script uses the following mapping for the generated .env file: