### Terraform Setup Action Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/index.md Use the hashicorp/setup-terraform action to install Terraform. Ensure the wrapper option is disabled for compatibility with Terramate. ```yaml - uses: hashicorp/setup-terraform@v3 with: terraform_wrapper: false ``` -------------------------------- ### OpenTofu Setup Action Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/index.md Use the opentofu/setup-opentofu action to install OpenTofu. Ensure the wrapper option is disabled for compatibility with Terramate. ```yaml - uses: opentofu/setup-opentofu@v1 with: tofu_wrapper: false ``` -------------------------------- ### Setup Script for CI Environment Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/gitlab-ci/index.md Installs essential tools like Terraform and Terramate by downloading and extracting them into the PATH. Ensure the versions specified are compatible with your project. ```yaml .setup: script: - apk add unzip git bash curl jq - wget https://releases.hashicorp.com/terraform/1.5.7/terraform_1.5.7_linux_amd64.zip -O /tmp/terraform.zip - unzip /tmp/terraform.zip -d /tmp - mv /tmp/terraform /bin - wget https://github.com/terramate-io/terramate/releases/download/v0.9.1/terramate_0.9.1_linux_x86_64.tar.gz -O /tmp/terramate.tar.gz - tar xzf /tmp/terramate.tar.gz -C /tmp - mv /tmp/terramate /bin ``` -------------------------------- ### Install OpenTofu Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/drift-check-workflow.md Installs a specific version of OpenTofu. Set `tofu_wrapper` to `false` if not using a wrapper. ```yaml # # Uncomment this if using OpenTofu # - name: Install OpenTofu # uses: opentofu/setup-opentofu@v1 # with: # tofu_version: 1.10.3 # tofu_wrapper: false ``` -------------------------------- ### Install necessary packages with asdf Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/bitbucket-pipelines/index.md This script installs unzip and jq, clones the asdf version manager, adds Terraform and Terramate plugins, and installs them. It relies on a .tool-versions file for specific versions. ```bash #!/bin/bash set -euo pipefail apt-get install -y unzip jq git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0 && . ~/.asdf/asdf.sh asdf plugin add terraform asdf plugin add terramate asdf install ``` -------------------------------- ### Basic Component Instantiation Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/blocks/component.md Instantiate a component with a local source path and specific input values. ```hcl component "vpc" { source = "../components/vpc" inputs { cidr_block = "10.0.0.0/16" region = "us-east-1" } } ``` -------------------------------- ### Start Development Server with pnpm Source: https://github.com/terramate-io/terramate-docs/blob/main/README.md Run this command to compile and start the development server with hot-reloading enabled. This is used for active development. ```sh pnpm start ``` -------------------------------- ### Install Project Dependencies with pnpm Source: https://github.com/terramate-io/terramate-docs/blob/main/README.md Use this command to install all necessary project dependencies. Ensure pnpm is installed globally. ```sh pnpm install ``` -------------------------------- ### Install Terramate using Go (Latest Version) Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Install the latest release of the Terramate CLI and language server using the Go toolchain. ```sh go install github.com/terramate-io/terramate/cmd/...@latest ``` -------------------------------- ### OpenTofu Deployment Workflow Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/deployment-workflow.md This workflow automates OpenTofu deployments for changed Terramate stacks. It includes steps for checking out code, installing Terramate and OpenTofu, authenticating with cloud providers (commented out examples for Azure), and running OpenTofu init and apply commands on changed stacks. ```yaml name: OpenTofu Deployment on: push: branches: - main jobs: deploy: name: Deploy OpenTofu changes in changed Terramate stacks permissions: id-token: write contents: read runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} fetch-depth: 0 - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" # Comment this out if not using Terragrunt - name: Install Terragrunt uses: autero1/action-terragrunt@v3 with: terragrunt-version: 0.83.2 token: ${{ github.token }} # Uncomment this if using OpenTofu - name: Install OpenTofu uses: opentofu/setup-opentofu@v1 with: tofu_version: 1.10.3 tofu_wrapper: false - name: List changed stacks id: list run: terramate list --changed # # Comment this step out if not using AWS # - name: Configure AWS credentials via OIDC # if: steps.list.outputs.stdout # id: auth # uses: aws-actions/configure-aws-credentials@v4 # with: # aws-region: CHANGEME_AWS_REGION # role-to-assume: CHANGEME_IAM_ROLE_ARN # # Uncomment this if using Google Cloud # - name: Authenticate to Google Cloud # if: steps.list.outputs.stdout # id: auth # uses: google-github-actions/auth@v2 # with: # workload_identity_provider: CHANGEME_WORKLOAD_IDENTITY_PROVIDER # service_account: CHANGEME_SERVICE_ACCOUNT_EMAIL # # Uncomment this if using Microsoft Azure # - name: Configure Azure credentials # if: steps.list.outputs.stdout # id: auth # uses: azure/login@v2 # with: # client-id: CHANGEME_AZURE_CLIENT_ID # tenant-id: CHANGEME_AZURE_TENANT_ID # subscription-id: CHANGEME_AZURE_SUBSCRIPTION_ID - name: Run OpenTofu init on changed stacks if: steps.list.outputs.stdout id: init run: | terramate run \ --parallel 1 \ --changed \ -- \ tofu init - name: Apply planned changes on changed stacks if: steps.list.outputs.stdout id: apply run: | terramate run \ --parallel 5 \ --changed \ -- \ tofu apply -input=false -auto-approve -lock-timeout=5m ``` -------------------------------- ### Install Terramate using Go (Specific Version) Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Install a specific version of the Terramate CLI and language server using the Go toolchain. ```sh go install github.com/terramate-io/terramate/cmd/...@ ``` -------------------------------- ### Example Date Formatting Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_formatdate.md Demonstrates various date and time formats achievable with tm_formatdate using different specification strings. ```sh tm_formatdate("DD MMM YYYY hh:mm ZZZ", "2018-01-02T23:12:01Z") 02 Jan 2018 23:12 UTC ``` ```sh tm_formatdate("EEEE, DD-MMM-YY hh:mm:ss ZZZ", "2018-01-02T23:12:01Z") Tuesday, 02-Jan-18 23:12:01 UTC ``` ```sh tm_formatdate("EEE, DD MMM YYYY hh:mm:ss ZZZ", "2018-01-02T23:12:01-08:00") Tue, 02 Jan 2018 23:12:01 -0800 ``` ```sh tm_formatdate("MMM DD, YYYY", "2018-01-02T23:12:01Z") Jan 02, 2018 ``` ```sh tm_formatdate("HH:mmaa", "2018-01-02T23:12:01Z") 11:12pm ``` -------------------------------- ### Install Terramate on Windows Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/getting-started/index.md Download the Terramate binary directly from the GitHub releases page for Windows installation. ```sh # Download the binary from https://github.com/terramate-io/terramate/releases ``` -------------------------------- ### Create a stack with custom metadata Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/stacks/create.md This example shows how to create a stack and simultaneously define its `name` and `description` metadata. The `id` is automatically generated. ```sh terramate create \ stacks/vpc \ --name "Main VPC" \ --description "Stack to manage the main VPC" ``` -------------------------------- ### Map Block Syntax Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/blocks/map.md This example demonstrates the basic syntax for using the `map` block within a `globals` block to process a list of orders and calculate total spending per name, with nested mapping for products. ```hcl globals { map totals { for_each = global.orders iterator = per_name key = per_name.new.name value { total_spent = tm_try(per_name.old.total_spent, 0) + per_name.new.price map per_product { for_each = [for v in global.orders : v if v.name == per_name.new.name] iterator = per_product key = per_product.new.product value { total = tm_try(per_product.old.total, 0) + per_product.new.price } } } } } ``` -------------------------------- ### Generate HCL Block Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/code-generation/generate-hcl.md This example shows a basic configuration of the generate_hcl block, including setting a message and defining an argument reference. ```hcl generate_hcl { content = "message = \"'global.is_enabled' needs to be set to either true or false\"" argument_reference { message = "'global.is_enabled' needs to be set to either true or false" } } ``` -------------------------------- ### Install Terramate with Asdf Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Add the Terramate plugin to Asdf and install the latest version. ```sh asdf plugin add terramate asdf install terramate latest ``` -------------------------------- ### Install Terramate Shell Completions Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Install command autocompletion for bash, zsh, and fish shells by running this command and opening a new shell session. ```sh terramate install-completions ``` -------------------------------- ### Assert Block Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/blocks/assert.md An example demonstrating how to use the assert block to check if two global variables are equal, providing a detailed error message if they are not. ```hcl assert { assertion = global.a == global.b message = "assertion failed, details: ${global.a} != ${global.b}" } ``` -------------------------------- ### Install Terramate CLI on Ubuntu/Debian Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Add the Terramate repository and install the CLI on Ubuntu and Debian-based systems. ```sh echo "deb [trusted=yes] https://repo.terramate.io/apt/ /" \ | sudo tee /etc/apt/sources.list.d/terramate.list apt update apt install terramate ``` -------------------------------- ### List Input (Batch Processing) Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_slug.md Illustrates using tm_slug with a list of strings for efficient batch slug generation. ```APIDOC ## List Input (Batch Processing) ### Example ```hcl locals { product_names = ["Product A", "Service/B", "Component C!"] product_slugs = tm_slug(local.product_names) # Returns: ["product-a", "service-b", "component-c-"] # Eliminates need for list comprehension: # Old way: [for s in local.product_names : tm_slug(s)] # New way: tm_slug(local.product_names) } ``` ``` -------------------------------- ### Example Remote Package Manifest Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/concepts/collections.md An example of a `terramate_packages.json` file used by remote catalogs to expose bundles and components. This file lists available bundles and components with their paths, names, classes, and versions. ```json [ { "name": "My Catalog", "description": "Contains examples", "bundles": [ { "path": "/bundles/my-bundle", "name": "Example bundle", "class": "my-org/my-bundle", "version": "1.0.0" } ], "components": [ { "path": "/components/my-component", "name": "Example component", "class": "my-org/my-component", "version": "1.0.0" } ] } ] ``` -------------------------------- ### tm_trim Examples Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_trim.md Demonstrates various use cases for the `tm_trim` function. ```APIDOC ## Examples ### Example 1: Trimming punctuation ```hcl result = tm_trim("?!hello?!", "!?") // result is "hello" ``` ### Example 2: Trimming specific characters ```hcl result = tm_trim("foobar", "far") // result is "oob" ``` ### Example 3: Trimming whitespace and punctuation ```hcl result = tm_trim(" hello! world.! ", "! ") // result is "hello! world." ``` ``` -------------------------------- ### Initialize OpenTofu with Terramate Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/drift-check-workflow.md Initializes the OpenTofu environment for a project managed by Terramate. Ensure Terramate is installed and configured. ```yaml - name: Initialize OpenTofu id: init run: | terramate run \ --parallel 1 \ -- \ tofu init -lock-timeout=5m ``` -------------------------------- ### Setup Terragrunt Action Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/drift-check-workflow.md Sets up the Terragrunt action for use in a GitHub Actions workflow. Requires specifying the Terragrunt version and a GitHub token. ```yaml - name: Setup Terragrunt uses: autero1/action-terragrunt@v3 with: terragrunt-version: 0.83.2 token: ${{ github.token }} ``` -------------------------------- ### tm_range Sequence Generation Examples Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_range.md Demonstrates various ways to use tm_range to generate number sequences with different arguments. ```shell tm_range(3) [ 0, 1, 2, ] ``` ```shell tm_range(1, 4) [ 1, 2, 3, ] ``` ```shell tm_range(1, 8, 2) [ 1, 3, 5, 7, ] ``` ```shell tm_range(1, 4, 0.5) [ 1, 1.5, 2, 2.5, 3, 3.5, ] ``` ```shell tm_range(4, 1) [ 4, 3, 2, ] ``` ```shell tm_range(10, 5, -2) [ 10, 8, 6, ] ``` -------------------------------- ### Get Stack Name Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/experimental/experimental-get-config-value.md Retrieve the stack name for a specific stack using the experimental get-config-value command. This command is experimental and subject to change. ```bash terramate experimental get-config-value 'terramate.stack.name' ``` -------------------------------- ### Scaffold a Bundle via CLI Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/how-to/instantiate-bundle-cli.md Use this command to start the bundle instantiation process. It prompts you to select a bundle and fill in required inputs, then writes the instantiation file. ```bash terramate scaffold ``` -------------------------------- ### Add .gitignore for Terraform Files Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/getting-started/index.md Prepare your git repository to ignore temporary Terraform files by creating a .gitignore file. This is useful for quickstart guides. ```bash # NOTE: You might not want to add state and lock file here # This is just convenient when running the quickstart guide $ cat <.gitignore .terraform .terraform.lock.hcl *.tfstate terraform.tfstate terraform.tfstate.backup *.tfplan EOF $ git add .gitignore $ git commit -m 'Add .gitignore' ``` -------------------------------- ### Count all lowercase alphabetic substrings Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_regexall.md This example shows how to count the number of matches found by tm_regexall. It uses tm_length to get the size of the list returned by tm_regexall. ```sh tm_length(regexall("[a-z]+", "1234abcd5678efgh9")) 2 ``` -------------------------------- ### Create a Package Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/package/package-create.md Use this command to create a package from the current directory. Specify the output directory for the package contents. Optional flags allow for generating only the manifest, overriding the package location, and setting a custom name and description for the catalog. ```sh terramate package create \ [--manifest-only] \ [--location ""] \ [--name ""] \ [--description ""] ``` -------------------------------- ### Terragrunt Workflow Setup Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/preview-workflow.md This YAML configuration sets up a GitHub Actions workflow for Terragrunt. It defines triggers, jobs, permissions, and steps for checking out code, installing Terramate, Terraform, and Terragrunt, and formatting checks. ```yaml name: Terragrunt Preview on: pull_request: jobs: preview: name: Plan Terragrunt changes in changed Terramate stacks runs-on: ubuntu-latest permissions: id-token: write contents: read pull-requests: write checks: read steps: - name: Prepare pull request preview comment if: github.event.pull_request uses: marocchino/sticky-pull-request-comment@v2 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} header: preview message: | ## Preview of Terragrunt changes in ${{ github.event.pull_request.head.sha }} :warning: preview is being created... please stand by! - name: Checkout uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} fetch-depth: 0 - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" # Comment this out if not using Terraform - name: Install Terraform uses: hashicorp/setup-terraform@v3 with: terraform_version: 1.12.2 terraform_wrapper: false # Uncomment this if using OpenTofu # - name: Install OpenTofu # uses: opentofu/setup-opentofu@v1 # with: # tofu_version: 1.10.3 # tofu_wrapper: false - name: Setup Terragrunt uses: autero1/action-terragrunt@v3 with: terragrunt-version: 0.83.2 token: ${{ github.token }} - name: Check Terramate formatting run: terramate fmt --check - name: Check Terragrunt formatting run: terragrunt fmt --terragrunt-check - name: List changed stacks id: list run: terramate list --changed # # Comment this step out if not using AWS - name: Configure AWS credentials via OIDC if: steps.list.outputs.stdout id: auth uses: aws-actions/configure-aws-credentials@v4 with: aws-region: CHANGEME_AWS_REGION role-to-assume: CHANGEME_IAM_ROLE_ARN # # Uncomment this if using Google Cloud # - name: Authenticate to Google Cloud # if: steps.list.outputs.stdout # id: auth # uses: google-github-actions/auth@v2 # with: # workload_identity_provider: CHANGEME_WORKLOAD_IDENTITY_PROVIDER # service_account: CHANGEME_SERVICE_ACCOUNT_EMAIL # # Uncomment this if using Microsoft Azure # - name: Configure Azure credentials # if: steps.list.outputs.stdout # id: auth # uses: azure/login@v2 # with: # client-id: CHANGEME_AZURE_CLIENT_ID # tenant-id: CHANGEME_AZURE_TENANT_ID # subscription-id: CHANGEME_AZURE_SUBSCRIPTION_ID - name: Initialize Terragrunt in changed stacks ``` -------------------------------- ### Basic Component Instantiation Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/blocks/component.md Instantiate a component by referencing its source and providing input values. ```hcl component "my-component" { source = "github.com/org/catalog//components/my-component?ref=v1.0.0" inputs { name = "my-service" visibility = "public" } } ``` -------------------------------- ### Terragrunt Deployment Workflow Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/deployment-workflow.md This workflow automates Terragrunt deployments for changed Terramate stacks. It includes steps for checking out code, installing Terramate and Terragrunt, authenticating with cloud providers (commented out examples for AWS, Google Cloud, and Azure), and running Terragrunt init and apply commands on changed stacks. ```yaml name: Terragrunt Deployment on: push: branches: - main jobs: deploy: name: Deploy Terragrunt changes in changed Terramate stacks permissions: id-token: write contents: read runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} fetch-depth: 0 - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" # Comment this out if not using Terraform - name: Install Terraform uses: hashicorp/setup-terraform@v3 with: terraform_version: 1.12.2 terraform_wrapper: false # Uncomment this if using OpenTofu # - name: Install OpenTofu # uses: opentofu/setup-opentofu@v1 # with: # tofu_version: 1.10.3 # tofu_wrapper: false - name: Setup Terragrunt uses: autero1/action-terragrunt@v3 with: terragrunt-version: 0.83.2 token: ${{ github.token }} - name: List changed stacks id: list run: terramate list --changed # # Comment this step out if not using AWS - name: Configure AWS credentials via OIDC if: steps.list.outputs.stdout id: auth uses: aws-actions/configure-aws-credentials@v4 with: aws-region: CHANGEME_AWS_REGION role-to-assume: CHANGEME_IAM_ROLE_ARN # # Uncomment this if using Google Cloud # - name: Authenticate to Google Cloud # if: steps.list.outputs.stdout # id: auth # uses: google-github-actions/auth@v2 # with: # workload_identity_provider: CHANGEME_WORKLOAD_IDENTITY_PROVIDER # service_account: CHANGEME_SERVICE_ACCOUNT_EMAIL # # Uncomment this if using Microsoft Azure # - name: Configure Azure credentials # if: steps.list.outputs.stdout # id: auth # uses: azure/login@v2 # with: # client-id: CHANGEME_AZURE_CLIENT_ID # tenant-id: CHANGEME_AZURE_TENANT_ID # subscription-id: CHANGEME_AZURE_SUBSCRIPTION_ID - name: Run Terragrunt init in each changed stacks if: steps.list.outputs.stdout id: init run: | terramate run \ --parallel 1 \ --changed \ -- \ terragrunt init - name: Apply planned changes on changed stacks if: steps.list.outputs.stdout id: apply run: | terramate run \ --parallel 5 \ --changed \ -- \ terragrunt apply -input=false -auto-approve -lock-timeout=5m ``` -------------------------------- ### Define a promotion chain with environments Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/blocks/environment.md Configure a promotion chain by setting the `promote_from` argument to link environments sequentially, such as dev to staging, and staging to production. ```hcl # environments/dev.tm.hcl environment { id = "dev" name = "Development" description = "Development environment for testing changes" } # environments/staging.tm.hcl environment { id = "staging" name = "Staging" description = "Pre-production environment" promote_from = "dev" } # environments/prod.tm.hcl environment { id = "prod" name = "Production" description = "Production environment" promote_from = "staging" } ``` -------------------------------- ### Initialize Terraform/OpenTofu Stacks Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/getting-started/index.md Orchestrate the initialization of your Terraform or OpenTofu stacks using the terramate run command. This prepares the stacks for use. ```sh $ terramate run terraform init ``` ```sh $ terramate run tofu init ``` -------------------------------- ### Install Terramate CLI Source: https://context7.com/terramate-io/terramate-docs/llms.txt Installs the Terramate CLI using various package managers and methods across different platforms. Ensure you have the necessary permissions for system-wide installations. ```sh # macOS brew install terramate ``` ```sh # Ubuntu / Debian echo "deb [trusted=yes] https://repo.terramate.io/apt/ /" \ | sudo tee /etc/apt/sources.list.d/terramate.list apt update && apt install terramate ``` ```sh # Fedora / CentOS sudo tee /etc/yum.repos.d/terramate.repo <.value` and passed down explicitly. ```hcl component "members" { source = "/components/terramate.io/terramate-tf-github-organization-members/v1" inputs = { for k in tm_keys(bundle.input) : k => bundle.input[k].value } } ``` -------------------------------- ### Install Terramate CLI with Homebrew on macOS Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/installation.md Use Homebrew to install the Terramate CLI on macOS systems. ```sh brew install terramate ``` -------------------------------- ### Common Use Case: Configuration Keys Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_slug.md Demonstrates using tm_slug to create valid and consistent configuration keys from feature descriptions. ```APIDOC ### Configuration Keys ```hcl locals { feature_descriptions = [ "Advanced Analytics", "Real-time Notifications", "Multi-factor Authentication" ] config_keys = tm_slug(local.feature_descriptions) # Returns: ["advanced-analytics", "real-time-notifications", "multi-factor-authentication"] } ``` ``` -------------------------------- ### Install Terramate Action Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/drift-check-workflow.md Installs the Terramate action in a GitHub Actions workflow. Specify the desired Terramate version. ```yaml - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" ``` -------------------------------- ### Synchronize Preview to Terramate Cloud Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/run.md Use `--sync-preview` to synchronize the command as a new preview to Terramate Cloud. `--terraform-plan-file` or `--tofu-plan-file` is required for plan details. A custom layer can be set with `--layer`. ```bash terramate run --sync-preview --terraform-plan-file "./my-plan.tfplan" ``` ```bash terramate run --sync-preview --tofu-plan-file "./my-plan.tfplan" ``` ```bash terramate run --layer staging --sync-preview --terraform-plan-file "./my-plan.tfplan" ``` -------------------------------- ### Expand '~' in Path Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_pathexpand.md Expands a path starting with '~' to the user's home directory. If the path does not start with '~', it is returned as is. ```shell tm_pathexpand("~/.ssh/id_rsa") /home/steve/.ssh/id_rsa ``` ```shell tm_pathexpand("/etc/resolv.conf") /etc/resolv.conf ``` -------------------------------- ### Include All Dependencies Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/change-detection/index.md Use the `--include-all-dependencies` flag to add all direct and transitive dependencies of the selected stacks to the execution set. ```sh terramate list --include-all-dependencies ``` -------------------------------- ### Define a Bundle with a Component Instance Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/tutorials/create-a-component-and-bundle.md Create a new bundle definition directory and add a stack that includes an instance of the component. Wire bundle inputs as needed. ```hcl define bundle stack "example" { metadata { path = "stacks/example" name = "Example Stack" } component "example" { source = "/components/path/to/created-component" inputs = {} # wire bundle inputs as needed } } ``` -------------------------------- ### OpenTofu Preview Workflow Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/preview-workflow.md This workflow runs OpenTofu plan on changed stacks for pull requests. It includes steps for checking formatting, listing changed stacks, configuring cloud credentials, and initializing/validating/planning OpenTofu configurations. ```yaml name: OpenTofu Preview on: pull_request: jobs: preview: name: Plan OpenTofu changes in changed Terramate stacks runs-on: ubuntu-latest permissions: id-token: write contents: read pull-requests: write checks: read steps: - name: Checkout uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} fetch-depth: 0 - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" - name: Install OpenTofu uses: opentofu/setup-opentofu@v1 with: tofu_version: 1.10.3 tofu_wrapper: false - name: Check Terramate formatting run: terramate fmt --check - name: Check OpenTofu formatting run: tofu fmt -recursive -check -diff - name: List changed stacks id: list run: terramate list --changed # # Comment this step out if not using AWS - name: Configure AWS credentials via OIDC if: steps.list.outputs.stdout id: auth uses: aws-actions/configure-aws-credentials@v4 with: aws-region: CHANGEME_AWS_REGION role-to-assume: CHANGEME_IAM_ROLE_ARN ``` -------------------------------- ### Install Terraform and Terramate Packages Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/gitlab-ci/index.md Installs necessary packages including Terraform and Terramate. Ensure Terramate CLI version is at least 0.9.1. ```yaml .setup: script: - apk add unzip git bash curl jq - wget https://releases.hashicorp.com/terraform/1.9.0/terraform_1.9.0_linux_amd64.zip -O /tmp/terraform.zip - unzip /tmp/terraform.zip -d /tmp - mv /tmp/terraform /bin - wget https://github.com/terramate-io/terramate/releases/download/v0.9.1/terramate_0.9.1_linux_x86_64.tar.gz -O /tmp/terramate.tar.gz - tar xzf /tmp/terramate.tar.gz -C /tmp - mv /tmp/terramate /bin ``` -------------------------------- ### tm_one Examples with Lists Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_one.md Illustrates the behavior of tm_one with empty lists, single-element lists, and lists with multiple elements, showing expected outputs and error conditions. ```shell tm_one([]) null ``` ```shell tm_one(["hello"]) "hello" ``` ```shell tm_one(["hello", "goodbye"]) Error: Invalid function argument Invalid value for "list" parameter: must be a list, set, or tuple value with either zero or one elements. ``` -------------------------------- ### Generated File Header Example Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/code-generation/index.md This is an example of a header comment that is automatically added to generated files. It indicates that the file is auto-generated and should not be edited manually. ```hcl // TERRAMATE: GENERATED AUTOMATICALLY DO NOT EDIT .... ``` -------------------------------- ### Example Usage of terramate.bundles Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/reference/variables.md An example showing how to construct a list of allowed values by iterating over bundle exports and extracting specific data. This usage pattern is deprecated; prefer `tm_bundles()` and `tm_bundle()`. ```hcl allowed_values = tm_concat( [{ name = "-- None --", value = null }], [for parent in tm_try( tm_joinlist("/", tm_tree(tm_values( terramate.bundles["terramate.io/tf-github-team"])[*].export.team_tuple.value ) ), []) : { name = parent, value = tm_reverse(tm_split("/", parent))[0] } ] ) ``` -------------------------------- ### Create Component from Current Directory Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/component/component-create.md Run this command when you are inside the module directory to create a component. It defaults to the current directory (`.`). ```sh cd path/to/module terramate component create . ``` -------------------------------- ### Create a Component from a Module Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/tutorials/create-a-component-and-bundle.md Navigate to your Terraform/OpenTofu module directory and run this command to create a new component. Review the generated metadata and inputs for the component. ```sh cd path/to/module terramate component create ``` -------------------------------- ### Get Current Timestamp Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_timestamp.md Call `tm_timestamp()` to get the current UTC timestamp in RFC 3339 format. The result changes every second, so it's applied only during the plan execution phase. ```sh tm_timestamp() 2018-05-13T07:44:12Z ``` -------------------------------- ### Scaffold and Generate in One Step Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/how-to/instantiate-bundle-cli.md This command combines scaffolding and code generation into a single step, streamlining the bundle instantiation workflow. ```bash terramate scaffold --generate ``` -------------------------------- ### tm_trimspace Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_trimspace.md Removes space characters from the start and end of a string. ```APIDOC ## `tm_trimspace` Function ### Description Removes any space characters from the start and end of the given string, following the Unicode definition of "space". ### Parameters * **input** (string) - The string to trim. ### Returns * (string) - The trimmed string. ### Example ``` tm_trimspace(" hello\n\n") // Output: "hello" ``` ``` -------------------------------- ### OpenTofu Preview Workflow Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/preview-workflow.md This is the main GitHub Actions workflow for OpenTofu. It sets up the environment, checks formatting, lists changed stacks, and generates an OpenTofu plan. ```yaml name: OpenTofu Preview on: pull_request: jobs: preview: name: Plan OpenTofu changes in changed Terramate stacks runs-on: ubuntu-latest permissions: id-token: write contents: read pull-requests: write checks: read steps: - name: Prepare pull request preview comment if: github.event.pull_request uses: marocchino/sticky-pull-request-comment@v2 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} header: preview message: | ## Preview of OpenTofu changes in ${{ github.event.pull_request.head.sha }} :warning: preview is being created... please stand by! - name: Checkout uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} fetch-depth: 0 - name: Install Terramate uses: terramate-io/terramate-action@v3 with: version: "0.14.0" - name: Install OpenTofu uses: opentofu/setup-opentofu@v1 with: tofu_version: 1.10.3 tofu_wrapper: false - name: Check Terramate formatting run: terramate fmt --check - name: Check OpenTofu formatting run: tofu fmt -recursive -check -diff - name: List changed stacks id: list run: terramate list --changed # # Comment this step out if not using AWS - name: Configure AWS credentials via OIDC if: steps.list.outputs.stdout id: auth uses: aws-actions/configure-aws-credentials@v4 with: aws-region: CHANGEME_AWS_REGION role-to-assume: CHANGEME_IAM_ROLE_ARN # # Uncomment this if using Google Cloud # - name: Authenticate to Google Cloud # if: steps.list.outputs.stdout # id: auth # uses: google-github-actions/auth@v2 # with: # workload_identity_provider: CHANGEME_WORKLOAD_IDENTITY_PROVIDER # service_account: CHANGEME_SERVICE_ACCOUNT_EMAIL # # Uncomment this if using Microsoft Azure # - name: Configure Azure credentials # if: steps.list.outputs.stdout # id: auth # uses: azure/login@v2 # with: # client-id: CHANGEME_AZURE_CLIENT_ID # tenant-id: CHANGEME_AZURE_TENANT_ID # subscription-id: CHANGEME_AZURE_SUBSCRIPTION_ID - name: Initialize OpenTofu in changed stacks if: steps.list.outputs.stdout id: init run: | terramate run \ --parallel 1 \ --changed \ -- \ tofu init -lock-timeout=5m - name: Validate OpenTofu configuration in changed stacks if: steps.list.outputs.stdout id: validate run: | terramate run \ --parallel 5 \ --changed \ -- \ tofu validate - name: Plan OpenTofu changes in changed stacks if: steps.list.outputs.stdout id: plan run: | terramate run \ --parallel 5 \ --changed \ --continue-on-error \ -- \ tofu plan -out out.otplan -lock=false # # Note: Due to a limitation in the size of a GitHub PR comment (65,536 characters), we are truncating the output if it's too long. For better and complete previews or changes consider Terramate Cloud. # # Note: Depending on the setup, you may need to add pr-comment.txt to your .gitignore to avoid any failures - name: Generate preview details if: steps.list.outputs.stdout id: comment run: | echo >>pr-comment.txt "## Preview of OpenTofu changes in ${{ github.event.pull_request.head.sha }}" echo >>pr-comment.txt echo >>pr-comment.txt "### Changed Stacks" ``` -------------------------------- ### Create a new stack with the CLI Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/stacks/create.md Use this command to create a new directory and a basic `stack.tm.hcl` file. The command automatically sets the stack's name, description, and a unique ID. ```sh terramate create ``` -------------------------------- ### Check Terramate Version Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/getting-started/index.md Verify the Terramate installation by checking the current version. ```sh $ terramate version ``` -------------------------------- ### Create a Terramate Package Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/how-to/package-catalog.md Use the `terramate package create` command to bundle your catalog into a distributable format. Specify the output directory for the package. ```sh terramate package create dist/catalog ``` -------------------------------- ### tm_yamlencode Examples Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_yamlencode.md Demonstrates how to use the tm_yamlencode function with different data structures. ```APIDOC ## `tm_yamlencode` Function Examples ### Example 1: Simple Map ```sh tm_yamlencode({"a":"b", "c":"d"}) ``` **Output:** ```yaml "a": "b" "c": "d" ``` ### Example 2: Map with List ```sh tm_yamlencode({"foo":[1, 2, 3], "bar": "baz"}) ``` **Output:** ```yaml "bar": "baz" "foo": - 1 - 2 - 3 ``` ### Example 3: Nested Map with List and Map ```sh tm_yamlencode({"foo":[1, {"a":"b","c":"d"}, 3], "bar": "baz"}) ``` **Output:** ```yaml "bar": "baz" "foo": - 1 - "a": "b" "c": "d" - 3 ``` **Note:** `tm_yamlencode` always uses YAML's "block style" for mappings and sequences, unless the mapping or sequence is empty. To generate flow-style YAML, use [`tm_jsonencode`](./tm_jsonencode.md) instead. ``` -------------------------------- ### Directory Structure Example for Child Stacks Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/stacks/index.md Illustrates a typical directory layout where 'db' and 'k8s' are child stacks of the 'vpc' stack. This structure signifies that the child stacks depend on the parent stack. ```shell . └── vpc ├── backend.tf ├── main.tf ├── terraform.tf ├── stack.tm.hcl │ ├── db │ ├── backend.tf │ ├── main.tf │ └── terraform.tf │ ├── stack.tm.hcl │ └── k8s ├── backend.tf ├── main.tf └── terraform.tf ├── stack.tm.hcl ``` -------------------------------- ### List all stacks recursively Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/list.md Use this command to list all Terramate stacks starting from the current directory. ```bash terramate list ``` -------------------------------- ### Create Component from Project-Relative Absolute Path Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/cmdline/component/component-create.md Use this command to create a component from a module specified by an absolute path relative to the project root. ```sh terramate component create /modules/s3-module ``` -------------------------------- ### Define tool versions for asdf Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/bitbucket-pipelines/index.md Specifies the exact versions of Terraform and Terramate to be installed via asdf. ```yaml terraform 1.9.3 terramate 0.11.5 ``` -------------------------------- ### Access Bundle Input with tm_bundle Source: https://github.com/terramate-io/terramate-docs/blob/main/catalyst/reference/functions/tm_bundle.md This example shows how to retrieve an input variable from a bundle. It's useful for accessing configuration parameters passed into a bundle. ```hcl locals { service_name = tm_bundle("example.com/my-bundle/v1", "main").input.name.value } ``` -------------------------------- ### Initialize Terragrunt with Terramate Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/automation/github-actions/drift-check-workflow.md Initializes the Terragrunt environment for a project managed by Terramate. Ensure Terramate and Terragrunt are installed. ```yaml - name: Initialize Terragrunt id: init run: | terramate run \ --parallel 1 \ -- \ terragrunt init -lock-timeout=5m ``` -------------------------------- ### Create a Second Stack Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/getting-started/index.md Follow the same procedure to create a second stack, providing a different name and description. ```sh $ terramate create \ --name "Bob" \ --description "Bob's first stack" \ stacks/bob ``` -------------------------------- ### Remove Prefix from String Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_trimprefix.md Use tm_trimprefix to remove a prefix from a string. If the string does not start with the specified prefix, it will be returned as is. ```sh tm_trimprefix("helloworld", "hello") world ``` ```sh tm_trimprefix("helloworld", "cat") helloworld ``` -------------------------------- ### Dependency Management with tm_tree Source: https://github.com/terramate-io/terramate-docs/blob/main/cli/reference/functions/tm_tree.md Demonstrates using `tm_tree` to establish a deployment order based on defined dependencies. The output represents a sequence that respects the hierarchical relationships. ```hcl locals { dependencies = [ [null, "base"], ["base", "network"], ["network", "compute"], ["compute", "application"] ] deployment_order = tm_tree(local.dependencies) # Returns deployment order respecting dependencies } ```