Terraspace Documentation

Timestamps behave differently depending on the scope of your log request:

• Multiple files: Timestamps are shown by default (e.g., when viewing all up logs across multiple stacks).
• Single file: Timestamps are not shown by default when you specify both an action and a specific stack (e.g., terraspace logs up network).

To explicitly show timestamps for a single stack log, use the --timestamps flag.

terraspace logs up network --timestamps

Terraspace provides simple commands to manage the lifecycle of your infrastructure stacks.

• terraspace up <stack_name>: Builds the stack in a cache directory and runs terraform init and terraform apply.
• terraspace down <stack_name>: Builds the stack in a cache directory and runs terraform destroy to clean up resources.

# Deploy a specific stack
terraspace up demo

# Destroy a specific stack
terraspace down demo

The terraspace all up command orchestrates the deployment of multiple stacks by grouping them into batches. Terraspace executes these batches in parallel to optimize deployment time. Before execution, Terraspace displays a list of the commands it will run and asks for confirmation.

After deployment, Terraspace provides a summary of the runs and the total time taken. Detailed logs for each stack are written to the log/up/<stack_name>.log directory for debugging. You can use the terraspace log command to view these logs.

$ terraspace all up
# Terraspace will list batches and ask: Are you sure? (y/N)

# Example output:
# Batch Run 1:
# Running: terraspace up c1 Logs: log/up/c1.log
# terraspace up c1:  Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

To enable TAB auto-completion for Terraspace commands and arguments in your shell, add the following command to your shell profile (e.g., .bashrc, .zshrc, or .bash_profile):

eval $(terraspace completion_script)

Once enabled, you can use the [TAB] key to autocomplete commands like terraspace up [TAB], stack names terraspace up name [TAB], or flags terraspace up name --[TAB].

Use the terraspace new shim command to generate a Terraspace shim. This shim is typically installed at /usr/local/bin/terraspace.

After generation, ensure that /usr/local/bin is included in your system $PATH so the terraspace command can be executed from any terminal session. You can verify the installation by running which terraspace.

$ terraspace new shim

To follow logs as they are generated (similar to tail -f), use the -f option. This is useful when running long-running operations like terraspace all up. Terraspace automatically checks for new logs every second and adds them to the stream.

terraspace logs -f

If the terraspace command is not found after generating the shim, you may need to manually add /usr/local/bin to your $PATH.

To do this permanently in a Bash environment, add the following line to your ~/.bash_profile and restart your terminal:

export PATH=/usr/local/bin:$PATH

Use the terraspace new plugin command to scaffold a new Terraspace plugin. This command generates a complete directory structure including Ruby templates, HCL templates, RSpec test suites, and necessary configuration files (like .gemspec, Gemfile, and Rakefile) to allow you to build custom provider logic for Terraspace.

The generated structure includes:

• Templates: HCL and Ruby templates for modules, stacks, and project configurations.
• Interfaces: Ruby files for implementing core plugin interfaces such as backend, config, expander, and layer.
• Testing: A pre-configured RSpec testing environment with fixtures and spec helpers.
• Boilerplate: Standard Ruby gem files and CLI entrypoints.

$ terraspace new plugin mycloud

To get started with Terraspace, you can generate a starter project using the new command, which includes examples and a specified cloud provider plugin. Once the project is created, you can use up to deploy a stack and down to destroy it.

Supported major cloud providers include aws, azurerm (Azure), and google (GCP).

# Generate a new project with AWS plugin and examples
terraspace new project infra --plugin aws --examples

# Navigate to the project
cd infra

# Deploy a demo stack
terraspace up demo

# Clean up and delete the demo stack
terraspace down demo

Use the terraspace check_setup command to verify that your environment meets the necessary requirements. This command checks your current Terraspace version and ensures that your installed Terraform binary is version v0.12.x or above.

$ terraspace check_setup