### Install dependencies and start development server

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

Use these yarn commands to install project dependencies and start the development server for the Terrakube UI.

```bash
yarn install
yarn dev
```

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

### Example .env file structure

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

This is an example of the .env file generated by the setupEnv.sh script. Values are placeholders and should be replaced with actual configuration.

```dotenv
REACT_APP_TERRAKUBE_API_URL=https://terrakubeUrl/api/v1/
REACT_APP_CLIENT_ID=terrakube-app
REACT_APP_AUTHORITY=https://dexUrl.com
REACT_APP_REDIRECT_URI=http://localhost:3000
REACT_APP_REGISTRY_URI=https://registryUrl.com
REACT_APP_SCOPE=email openid profile offline_access groups
REACT_APP_TERRAKUBE_SEND_COOKIES=false
```

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

### Initialize Development Environment

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

Executes the setup script during the Gitpod environment startup process. Must be run from the /workspace/terrakube folder if re-executed.

```bash
./scripts/setupDevelopmentEnvironment.sh
```

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

### Runtime environment variables example

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

Example of the env-config.js file structure, which is loaded by the UI at runtime. These values are dynamically configured.

```javascript
window._env_ = {
  REACT_APP_TERRAKUBE_API_URL: "https://8080-azbuilder-terrakube-c3n4h1c0xul.ws-us88.gitpod.io/api/v1/",
  REACT_APP_CLIENT_ID: "example-app",
  REACT_APP_AUTHORITY: "https://5556-azbuilder-terrakube-c3n4h1c0xul.ws-us88.gitpod.io/dex",
  REACT_APP_REDIRECT_URI: "https://3000-azbuilder-terrakube-c3n4h1c0xul.ws-us88.gitpod.io",
  REACT_APP_REGISTRY_URI: "https://8075-azbuilder-terrakube-c3n4h1c0xul.ws-us88.gitpod.io",
  REACT_APP_SCOPE: "email openid profile offline_access groups",
  REACT_APP_TERRAKUBE_SEND_COOKIES: "false",
}


```

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

### Run Terrakube Locally

Source: https://github.com/terrakube-io/terrakube/blob/main/telemetry-compose/README.md

Clone the repository and start the services using Docker Compose.

```bash
git clone https://github.com/AzBuilder/terrakube.git
cd terrakube/docker-compose
docker-compose up -d
```

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

### Run OpenBao in Development Mode

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/openbao-vault/README.md

Starts an OpenBao server in development mode with a specified root token. Ensure this is only used for development environments.

```shell
bao server -dev -dev-root-token-id="dev-only-token"
```

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

### Run Terrakube with Docker Compose

Source: https://github.com/terrakube-io/terrakube/blob/main/docker-compose/README.md

Starts Terrakube services in detached mode using docker-compose. This command assumes the previous steps for setup and certificate generation have been completed.

```bash
docker-compose up -d --force-recreate
```

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

### Generate Local CA Certificate with mkcert

Source: https://github.com/terrakube-io/terrakube/blob/main/docker-compose/README.md

Installs the mkcert local Certificate Authority into your system's trust store. This is a prerequisite for generating local HTTPS certificates.

```shell
mkcert -install
Created a new local CA 💥
The local CA is now installed in the system trust store! ⚡️
The local CA is now installed in the Firefox trust store (requires browser restart)! 🦊
```

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

### Get Terrakube Job Details with Steps

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve detailed information about a specific job, including its execution steps. The job status can be pending, waitingApproval, approved, queue, running, completed, noChanges, rejected, cancelled, or failed.

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/job/{jobId}?include=step" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Terrakube API - Get Access Token Request

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

This is an example request to obtain an access token after completing Dex Device Code Authentication. It is used to authenticate subsequent API calls.

```http
POST /oauth2/token HTTP/1.1
Host: 5556-terrakube-io-terrakube-XXXX.ws-us54.gitpod.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=terrakube&device_code=htlj4w73ftjfplinifqntp7ept6xaratvgauu2nj3nldlcgxjym
```

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

### GET /api/v1/organization/{orgId}/job/{jobId}?include=step

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieves details for a specific job, including its execution steps.

```APIDOC
## GET /api/v1/organization/{orgId}/job/{jobId}?include=step

### Description
Retrieves details for a specific job, including its execution steps.

### Method
GET

### Endpoint
/api/v1/organization/{orgId}/job/{jobId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization ID.
- **jobId** (string) - Required - The ID of the job.

#### Query Parameters
- **include** (string) - Optional - Set to "step" to include job steps in the response.

### Response
#### Success Response (200)
- **data** (object) - Contains the job details and its steps.

#### Response Example
```json
{
  "data": {
    "id": "{jobId}",
    "type": "job",
    "attributes": {
      "status": "running",
      "createdAt": "2023-10-27T10:00:00Z"
    },
    "steps": [
      {
        "id": "{stepId}",
        "type": "step",
        "attributes": {
          "name": "Plan",
          "status": "completed"
        }
      }
    ]
  }
}
```
```

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

### Terraform Plan Output with Vault Secret Retrieval

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/openbao-vault/README.md

Example output of a Terraform plan command when integrated with Terrakube and Vault. It shows the successful retrieval of a secret from Vault using the `vault_kv_secret_v2` data source.

```shell
user@pop-os:~/git/terrakube/vault$ terraform plan

Running plan in Terraform Cloud. 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://terrakube-api.platform.local/app/simple/vault/runs/run-1

Waiting for the plan to start...

***************************************
Running Terraform PLAN
***************************************
data.vault_kv_secret_v2.password: Reading...
data.vault_kv_secret_v2.password: Read complete after 0s [id=shared/data/kv/creds]

No changes. Your infrastructure matches the configuration.
```

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

### GET /api/v1/organization/{orgId}/job?filter[job]=workspace.id=={workspaceId}&sort=-createdDate

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Lists all jobs for a specific workspace, sorted by creation date in descending order.

```APIDOC
## GET /api/v1/organization/{orgId}/job?filter[job]=workspace.id=={workspaceId}&sort=-createdDate

### Description
Lists all jobs associated with a specific workspace, ordered by their creation date from newest to oldest.

### Method
GET

### Endpoint
/api/v1/organization/{orgId}/job

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization ID.

#### Query Parameters
- **filter[job]** (string) - Required - Filters jobs by workspace ID. Format: "workspace.id=={workspaceId}".
- **sort** (string) - Optional - Sorts the results. Use "-createdDate" for descending order (newest first).

### Response
#### Success Response (200)
- **data** (array) - A list of job objects.

#### Response Example
```json
{
  "data": [
    {
      "id": "{jobId1}",
      "type": "job",
      "attributes": {
        "status": "completed",
        "createdAt": "2023-10-27T10:00:00Z"
      }
    },
    {
      "id": "{jobId2}",
      "type": "job",
      "attributes": {
        "status": "running",
        "createdAt": "2023-10-27T09:30:00Z"
      }
    }
  ]
}
```
```

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

### Sample Organization Data Files

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

Paths to the XML files containing preloaded organization data for the API startup.

```text
api/src/main/resources/db/changelog/demo-data/aws.xml
api/src/main/resources/db/changelog/demo-data/gcp.xml
api/src/main/resources/db/changelog/demo-data/azure.xml
api/src/main/resources/db/changelog/demo-data/simple.xml
```

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

### Generate .env file with setupEnv.sh

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

Run this script to generate the .env file for local environment configuration. Ensure all required environment variables are defined beforehand.

```bash
./setupEnv.sh
```

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

### Initialize and Configure OpenBao for Terrakube

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/openbao-vault/README.md

Shell commands to set up OpenBao, including enabling authentication methods, creating users, configuring KV secrets, enabling JWT authentication, writing policies, and defining JWT roles. Ensure `VAULT_ADDR` is set correctly.

```shell
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
```

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

### Manage VCS Connections

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Create and list VCS connections for workspace triggers and module sources.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/vcs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "vcs",
      "attributes": {
        "name": "GitHub Enterprise",
        "description": "Corporate GitHub",
        "vcsType": "GITHUB",
        "clientId": "your-oauth-client-id",
        "clientSecret": "your-oauth-client-secret",
        "endpoint": "https://github.example.com",
        "apiUrl": "https://api.github.example.com",
        "connectionType": "OAUTH"
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/vcs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Terrakube API - Get OpenAPI Spec Request

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

This request retrieves the OpenAPI specification for the Terrakube API. This specification can be used to understand and interact with the API.

```http
GET /api/v1/openapi.yaml HTTP/1.1
Host: 5556-terrakube-io-terrakube-XXXX.ws-us54.gitpod.io
Authorization: Bearer <ACCESS_TOKEN>
```

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

### Manage Templates via API

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Create and list organization templates using the Terrakube API.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "template",
      "attributes": {
        "name": "Plan-Apply-Notify",
        "description": "Plan, apply, and send Slack notification",
        "version": "1.0.0",
        "tcl": "flow:\n  - type: terraformPlan\n    step: 100\n  - type: approval\n    step: 200\n    team: \"Platform\"\n  - type: terraformApply\n    step: 300"
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Retrieve Development Environment URL

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

Fetches the URL for the application running on port 3000 after startup is complete.

```bash
gp url 3000
```

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

### Terrakube Terraform Module Protocol - Get Versions Request

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

This request is part of testing the Terraform Module Protocol. It is used to retrieve the available versions for a specific Terraform module.

```http
GET /api/v1/terraform/module/versions/terrakube/terrakube/aws-vpc HTTP/1.1
Host: 5556-terrakube-io-terrakube-XXXX.ws-us54.gitpod.io
Authorization: Bearer <ACCESS_TOKEN>
```

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

### Manage Module Registry

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Register, list versions, and download modules from the private registry.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/module" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "module",
      "attributes": {
        "name": "vpc",
        "description": "AWS VPC module",
        "provider": "aws",
        "source": "https://github.com/org/terraform-aws-vpc"
      },
      "relationships": {
        "vcs": {
          "data": {
            "type": "vcs",
            "id": "{vcsId}"
          }
        }
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-registry.example.com/terraform/modules/v1/{organization}/{module}/{provider}/versions" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
curl -X GET "https://terrakube-registry.example.com/terraform/modules/v1/{organization}/{module}/{provider}/{version}/download" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Terraform Configuration for Vault Integration

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/openbao-vault/README.md

Terraform code to configure Terrakube cloud settings and the Vault provider. It includes skipping TLS verification and child token creation for simplicity in this example.

```terraform
terraform {
  cloud {
    hostname = "terrakube-api.platform.local"
    organization = "simple"
    workspaces {
      name = "vault"
    }
  }
}

provider vault {
  skip_tls_verify = true
  skip_child_token = true
  }

data "vault_kv_secret_v2" "password" {
  mount = "shared"
  name  = "kv/creds"
}
```

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

### Create Webhooks and Events

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Configure webhooks for VCS-triggered automation and define specific trigger conditions for those webhooks.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/webhook" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "webhook",
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspace",
            "id": "{workspaceId}"
          }
        }
      }
    }
  }'
```

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/webhook/{webhookId}/webhook_event" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "webhook_event",
      "attributes": {
        "event": "PUSH",
        "branch": "main",
        "path": "/terraform",
        "pathType": "PREFIX"
      }
    }
  }'
```

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

### Terrakube Terraform Module Protocol - Get Zip File Request

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

This request is part of testing the Terraform Module Protocol. It is used to download the zip archive of a specific version of a Terraform module.

```http
GET /api/v1/terraform/module/download/terrakube/terrakube/aws-vpc/1.0.0 HTTP/1.1
Host: 5556-terrakube-io-terrakube-XXXX.ws-us54.gitpod.io
Authorization: Bearer <ACCESS_TOKEN>
```

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

### Build Terrakube UI Docker image

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

Build a Docker image for the Terrakube UI using the provided Dockerfile. Tag the image as 'terrakube-ui:latest'.

```bash
docker build -t terrakube-ui:latest  .
```

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

### Deploy Terrakube via Docker Compose

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Commands to clone the repository, generate local certificates, configure networking, and launch the Terrakube platform.

```bash
git clone https://github.com/terrakube-io/terrakube.git
cd terrakube/docker-compose

mkcert -install
mkcert -key-file key.pem -cert-file cert.pem platform.local *.platform.local
cp $(mkcert -CAROOT)/rootCA.pem rootCA.pem

docker network create terrakube-network -d bridge --subnet 10.25.25.0/24 --gateway 10.25.25.254

docker-compose up -d
```

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

### Dex and LDAP Configuration Paths

Source: https://github.com/terrakube-io/terrakube/blob/main/development.md

Lists the file paths for OpenLDAP and Dex configuration files used in the development environment.

```text
scripts/setup/dex/config-ldap.ldif
```

```text
scripts/setup/dex/config-ldap.yaml
```

```text
scripts/template/dex/template-config-ldap.yaml
```

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

### List All Variables for a Workspace

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve a list of all variables configured for a specific workspace.

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace/{workspaceId}/variable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Retrieve OIDC Configuration

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Access OpenID Connect discovery endpoints to facilitate workload identity federation.

```bash
curl -X GET "https://terrakube-api.example.com/.well-known/openid-configuration"
```

```bash
curl -X GET "https://terrakube-api.example.com/.well-known/jwks"
```

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

### Manage Personal Access Tokens

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Create, list, and delete PATs for authenticating CLI tools and automation scripts.

```bash
curl -X POST "https://terrakube-api.example.com/pat/v1" \
  -H "Authorization: Bearer $OIDC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 30,
    "description": "CI/CD automation token"
  }'
```

```bash
curl -X GET "https://terrakube-api.example.com/pat/v1" \
  -H "Authorization: Bearer $OIDC_TOKEN"
```

```bash
curl -X DELETE "https://terrakube-api.example.com/pat/v1/{tokenId}" \
  -H "Authorization: Bearer $OIDC_TOKEN"
```

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

### Configure Local DNS Entries

Source: https://github.com/terrakube-io/terrakube/blob/main/telemetry-compose/README.md

Add these entries to your /etc/hosts file to resolve Terrakube services locally.

```bash
127.0.0.1 terrakube-api
127.0.0.1 terrakube-ui
127.0.0.1 terrakube-executor
127.0.0.1 terrakube-dex
127.0.0.1 terrakube-registry
```

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

### Migrate from Terraform Cloud

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Import workspaces, variables, and state from Terraform Cloud or Enterprise into Terrakube.

```bash
curl -X GET "https://terrakube-api.example.com/importer/tfcloud/workspaces?organization=my-tfc-org" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-TFC-Url: https://app.terraform.io" \
  -H "X-TFC-Token: $TFC_API_TOKEN"
```

```bash
curl -X GET "https://terrakube-api.example.com/importer/tfcloud/workspaces/{workspaceId}/varsets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-TFC-Url: https://app.terraform.io" \
  -H "X-TFC-Token: $TFC_API_TOKEN"
```

```bash
curl -X POST "https://terrakube-api.example.com/importer/tfcloud/workspaces" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-TFC-Url: https://app.terraform.io" \
  -H "X-TFC-Token: $TFC_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceOrganization": "my-tfc-org",
    "targetOrganization": "{orgId}",
    "workspaces": ["workspace-1", "workspace-2"],
    "importState": true,
    "importVariables": true
  }'
```

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

### Manage Teams and Permissions

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Create and list teams to define granular access control for workspaces, modules, and jobs.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/team" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "team",
      "attributes": {
        "name": "Platform",
        "manageWorkspace": true,
        "manageModule": true,
        "manageProvider": false,
        "manageVcs": true,
        "manageTemplate": true,
        "manageState": true,
        "manageJob": true,
        "planJob": true,
        "approveJob": true
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/team" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Configure Local DNS Entries

Source: https://github.com/terrakube-io/terrakube/blob/main/docker-compose/README.md

Adds entries to your /etc/hosts file to map local domain names to the Terrakube gateway IP address. This ensures local services resolve correctly.

```bash
10.25.25.253 terrakube.platform.local
10.25.25.253 terrakube-api.platform.local
10.25.25.253 terrakube-registry.platform.local
10.25.25.253 terrakube-dex.platform.local
```

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

### Manage Custom Providers

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Endpoints for registering, versioning, and downloading custom Terraform providers.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/provider" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "provider",
      "attributes": {
        "name": "custom",
        "description": "Custom internal provider"
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-registry.example.com/terraform/providers/v1/{organization}/{provider}/versions" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
curl -X GET "https://terrakube-registry.example.com/terraform/providers/v1/{organization}/{provider}/{version}/download/{os}/{arch}" \
  -H "Authorization: Bearer $TOKEN"
```

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

### Clone Terrakube and Generate HTTPS Certificates

Source: https://github.com/terrakube-io/terrakube/blob/main/docker-compose/README.md

Clones the Terrakube repository, navigates to the docker-compose directory, generates local HTTPS certificates for the platform domains using mkcert, and copies the CA root certificate.

```bash
git clone https://github.com/AzBuilder/terrakube.git
cd terrakube/docker-compose
mkcert -key-file key.pem -cert-file cert.pem platform.local *.platform.local
CAROOT=$(mkcert -CAROOT)/rootCA.pem
cp $CAROOT rootCA.pem
```

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

### List Global Variables

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve a list of all organization-level global variables.

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/globalvar" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Define Terraform Cloud and Provider Configuration

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/gcp/README.md

Configure the Terraform cloud block for Terrakube and the Google provider for resource management.

```terraform
terraform {

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

    workspaces {
      name = "terrakube_workspace_name"
    }
  }
}

provider "google" {
  project     = "my-gcp-project"
  region      = "us-central1"
  zone        = "us-central1-c"
}

resource "google_storage_bucket" "auto-expire" {
  name          = "mysuperbukcetname"
  location      = "US"
  force_destroy = true

  public_access_prevention = "enforced"
}
```

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

### Create a New Terrakube Job

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Use this endpoint to trigger a new Terraform run. Specify the template reference and the workspace ID.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/job" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "job",
      "attributes": {
        "templateReference": "Plan-and-Apply",
        "via": "API"
      },
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspace",
            "id": "{workspaceId}"
          }
        }
      }
    }
  }'
```

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

### Manage Organizations via REST API

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Operations for listing, creating, and retrieving organizations. Requires a valid bearer token and superuser privileges for creation.

```bash
# List all organizations
curl -X GET "https://terrakube-api.example.com/api/v1/organization" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"

# Response:
# {
#   "data": [{
#     "type": "organization",
#     "id": "d9b58bd3-f3fc-4056-a026-1163297e80a8",
#     "attributes": {
#       "name": "my-org",
#       "description": "My organization",
#       "executionMode": "remote"
#     },
#     "relationships": {
#       "workspace": { "data": [] },
#       "module": { "data": [] },
#       "provider": { "data": [] }
#     }
#   }]
# }

# Create a new organization (requires superuser)
curl -X POST "https://terrakube-api.example.com/api/v1/organization" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "organization",
      "attributes": {
        "name": "production-org",
        "description": "Production infrastructure organization",
        "executionMode": "remote"
      }
    }
  }'

# Get organization with related workspaces
curl -X GET "https://terrakube-api.example.com/api/v1/organization/d9b58bd3-f3fc-4056-a026-1163297e80a8?include=workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Open Telemetry Environment Variables

Source: https://github.com/terrakube-io/terrakube/blob/main/telemetry-compose/README.md

Environment variables required to enable the Open Telemetry Agent for Terrakube components.

```text
OTEL_JAVAAGENT_ENABLED=true
OTEL_TRACES_EXPORTER=jaeger
OTEL_EXPORTER_JAEGER_ENDPOINT=http://jaeger-all-in-one:14250
OTEL_SERVICE_NAME=TERRAKUBE-API
```

```text
OTEL_JAVAAGENT_ENABLED=true
OTEL_TRACES_EXPORTER=jaeger
OTEL_EXPORTER_JAEGER_ENDPOINT=http://jaeger-all-in-one:14250
OTEL_SERVICE_NAME=TERRAKUBE-REGISTRY
```

```text
OTEL_JAVAAGENT_ENABLED=true
OTEL_TRACES_EXPORTER=jaeger
OTEL_EXPORTER_JAEGER_ENDPOINT=http://jaeger-all-in-one:14250
OTEL_SERVICE_NAME=TERRAKUBE-EXECUTOR
```

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

### List Terrakube Jobs for a Workspace

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve a list of jobs associated with a specific workspace, sorted by their creation date in descending order.

```bash
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/job?filter[job]=workspace.id=={workspaceId}&sort=-createdDate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### POST /api/v1/organization/{orgId}/vcs

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Creates a new VCS connection for the organization.

```APIDOC
## POST /api/v1/organization/{orgId}/vcs

### Description
Integrates Terrakube with a version control provider.

### Method
POST

### Endpoint
https://terrakube-api.example.com/api/v1/organization/{orgId}/vcs

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID.

#### Request Body
- **data.attributes.name** (string) - Required - Name of the connection.
- **data.attributes.vcsType** (string) - Required - Type of VCS (GITHUB, GITLAB, BITBUCKET, AZURE_DEVOPS).
- **data.attributes.connectionType** (string) - Required - Connection method (OAUTH, GITHUB_APP_INSTALLATION).
```

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

### Create a Global Environment Variable

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Add an organization-level global environment variable. These are inherited by all workspaces and managed by superusers.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/globalvar" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "globalvar",
      "attributes": {
        "key": "TF_LOG",
        "value": "INFO",
        "description": "Terraform logging level",
        "category": "ENV",
        "sensitive": false,
        "hcl": false
      }
    }
  }'
```

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

### POST /api/v1/organization/{orgId}/workspace/{workspaceId}/schedule

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Creates a scheduled job for a specific workspace.

```APIDOC
## POST /api/v1/organization/{orgId}/workspace/{workspaceId}/schedule

### Description
Creates a new scheduled job to enable automated periodic execution.

### Method
POST

### Endpoint
https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace/{workspaceId}/schedule

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID.
- **workspaceId** (string) - Required - Workspace ID.

#### Request Body
- **data.attributes.cron** (string) - Required - Cron expression for scheduling.
- **data.attributes.templateReference** (string) - Required - Reference to the template to execute.
- **data.attributes.enabled** (boolean) - Required - Whether the schedule is active.
```

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

### Terraform Remote Backend Integration

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Configure Terraform to use Terrakube as a remote backend and interact with the TFC-compatible API.

```bash
curl -X GET "https://terrakube-api.example.com/remote/tfe/v2/ping"
```

```bash
curl -X POST "https://terrakube-api.example.com/remote/tfe/v2/runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "runs",
      "attributes": {
        "message": "Triggered via API"
      },
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspaces",
            "id": "{workspaceId}"
          }
        }
      }
    }
  }'
```

```bash
curl -X GET "https://terrakube-api.example.com/remote/tfe/v2/organizations/{orgName}/workspaces/{workspaceName}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Docker Compose configuration for Terrakube UI

Source: https://github.com/terrakube-io/terrakube/blob/main/ui/README.md

This Docker Compose configuration defines how to run the Terrakube UI service. It maps the UI image and mounts the env-config.js file.

```yaml
version: "3.8"
services:
  terrakube-ui:
    image: terrakube-ui:latest
    container_name: terrakube-ui
    volumes:
      - ./env-config.js:/app/env-config.js
    ports:
      - 8080:8080 
```

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

### Configure Terrakube Variables

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/gcp/README.md

Define the required Terrakube and GCP project variables in a variables.auto.tfvars file.

```terraform
terrakube_token = "TERRAKUBE_PERSONAL_ACCESS_TOKEN"
terrakube_hostname = "terrakube-api.mydomain.com"
terrakube_organization_name = "simple"
terrakube_workspace_name = "dynamic-workspace"
gcp_project_id = "my-gcp-project"
```

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

### Manage Scheduled Jobs

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Create and disable automated workspace schedules using cron expressions.

```bash
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace/{workspaceId}/schedule" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "schedule",
      "attributes": {
        "cron": "0 0 * * *",
        "templateReference": "Plan-Only",
        "description": "Nightly drift detection",
        "enabled": true
      }
    }
  }'
```

```bash
curl -X PATCH "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace/{workspaceId}/schedule/{scheduleId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "schedule",
      "id": "{scheduleId}",
      "attributes": {
        "enabled": false
      }
    }
  }'
```

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

### Configure Terrakube Variables

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/azure/README.md

Set Terraform variables in 'variables.auto.tfvars' for Terrakube integration. Ensure the private key is in PKCS8 format.

```terraform
terrakube_token                          = "TERRAKUBE_PERSONAL_ACCESS_TOKEN"
terrakube_api_hostname                   = "TERRAKUBE-API.MYCLUSTER.COM"
terrakube_federated_credentials_audience = "api://AzureADTokenExchange"
terrakube_organization_name              = "simple"
terrakube_workspace_name                 = "dynamic-azure"
```

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

### Configure Terrakube variables

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/aws/README.md

Define the required Terrakube connection and authentication variables in a variables.auto.tfvars file.

```terraform
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"
```

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

### Manage Workspaces via REST API

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Operations for listing, creating, updating, and filtering workspaces within an organization. Replace {orgId} and {workspaceId} with actual resource identifiers.

```bash
# List workspaces in an organization
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"

# Create a workspace connected to a Git repository
curl -X POST "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "workspace",
      "attributes": {
        "name": "aws-production",
        "description": "AWS production infrastructure",
        "source": "https://github.com/org/terraform-aws",
        "branch": "main",
        "folder": "/environments/prod",
        "terraformVersion": "1.5.7",
        "iacType": "terraform",
        "executionMode": "remote"
      },
      "relationships": {
        "vcs": {
          "data": {
            "type": "vcs",
            "id": "vcs-uuid-here"
          }
        }
      }
    }
  }'

# Update workspace settings
curl -X PATCH "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace/{workspaceId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "workspace",
      "id": "{workspaceId}",
      "attributes": {
        "locked": true,
        "lockDescription": "Maintenance in progress",
        "terraformVersion": "1.6.0"
      }
    }
  }'

# Filter workspaces by tag
curl -X GET "https://terrakube-api.example.com/api/v1/organization/{orgId}/workspace?filter[workspace]=workspaceTag.tag.name==production" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json"
```

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

### Create Docker Network for Terrakube

Source: https://github.com/terrakube-io/terrakube/blob/main/docker-compose/README.md

Creates a dedicated Docker bridge network for Terrakube with a specified subnet and gateway. This network isolates Terrakube services.

```bash
docker network create terrakube-network -d bridge --subnet 10.25.25.0/24 --gateway 10.25.25.254
```

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

### Define Terraform cloud and provider configuration

Source: https://github.com/terrakube-io/terrakube/blob/main/dynamic-credential-setup/aws/README.md

Configure the Terraform cloud block to point to the Terrakube API and define the AWS provider for resource management.

```terraform
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"
  }
}
```

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

### Manage Terraform State

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve current Terraform state files for a specific workspace.

```bash
curl -X GET "https://terrakube-api.example.com/tfstate/v1/organization/{orgId}/workspace/{workspaceId}/state/terraform.tfstate" \
  -H "Authorization: Bearer $TOKEN"
```

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

### POST /api/v1/organization/{orgId}/module

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Publishes a new module entry to the private registry.

```APIDOC
## POST /api/v1/organization/{orgId}/module

### Description
Creates a module entry in the private module registry.

### Method
POST

### Endpoint
https://terrakube-api.example.com/api/v1/organization/{orgId}/module

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID.

#### Request Body
- **data.attributes.name** (string) - Required - Module name.
- **data.attributes.provider** (string) - Required - Provider name (e.g., aws).
- **data.attributes.source** (string) - Required - VCS source URL.
- **data.relationships.vcs.data.id** (string) - Required - VCS connection ID.
```

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

### POST /api/v1/organization/{orgId}/template

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Creates a new custom template for workflow execution.

```APIDOC
## POST /api/v1/organization/{orgId}/template

### Description
Creates a new custom template within an organization.

### Method
POST

### Endpoint
https://terrakube-api.example.com/api/v1/organization/{orgId}/template

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier of the organization.

#### Request Body
- **data** (object) - Required - The template resource object.
- **data.attributes.name** (string) - Required - Name of the template.
- **data.attributes.description** (string) - Optional - Description of the template.
- **data.attributes.version** (string) - Required - Version string.
- **data.attributes.tcl** (string) - Required - Terraform Control Language (TCL) definition.
```

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

### Manage Terraform State Versions

Source: https://context7.com/terrakube-io/terrakube/llms.txt

Retrieve historical state versions or perform a rollback to a specific state version using the Terrakube API.

```bash
curl -X GET "https://terrakube-api.example.com/tfstate/v1/organization/{orgId}/workspace/{workspaceId}/state/{historyId}.json" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
curl -X PUT "https://terrakube-api.example.com/tfstate/v1/organization/{orgId}/workspace/{workspaceId}/rollback/{historyId}.json" \
  -H "Authorization: Bearer $TOKEN"
```