thothctl

Project Conversion

The thothctl project convert command allows you to convert between different project formats, create templates from projects, and generate projects from templates. This flexibility enables efficient reuse of code and standardization across your organization.

Command Syntax

thothctl project convert [OPTIONS]

Options

Option	Description
`-br, --branch-name TEXT`	Branch name for Terramate stacks
`-tpt, --template-project-type`	Project type: `terraform`, `terraform-terragrunt`, `terragrunt`, `tofu`, `cdkv2`, `terraform_module`, `custom`
`-mtem, --make-template`	Create template from project
`-mpro, --make-project`	Create project from template
`-tm, --make-terramate-stacks`	Create Terramate stack for advanced deployments
`--help`	Show help message and exit

Note: --make-template, --make-project, and --make-terramate-stacks are mutually exclusive — only one can be used per invocation.

Prerequisites

For --make-template to work non-interactively, your project must have a [project_properties] section in .thothcf.toml:

[project_properties]
project_name = "my-project"
deployment_region = "us-east-1"
backend_bucket = "my-project-tfstate"
backend_region = "us-east-2"
owner = "my-team"
client = "my-org"
backend_dynamodb = "db-terraform-lock"
environment = "dev"
cloud_provider = "aws"
deployment_profile = "default"
backend_profile = "default"

If this section is missing, ThothCTL will prompt interactively for each value.

Conversion Types

Project to Template

Converting a project to a template allows you to create a reusable pattern that can be shared across your organization. This is useful for standardizing infrastructure deployments and ensuring consistency.

# Convert the current project to a template
thothctl project convert --make-template --template-project-type terraform-terragrunt

# Specify a different project type
thothctl project convert --make-template --template-project-type terraform

When converting a project to a template, ThothCTL:

Reads [project_properties] from .thothcf.toml to identify values to parameterize
Replaces those values with #{placeholder}# expressions in all project files (.tf, .hcl, .tfvars, etc.)
Saves the template to ~/.thothcf/<project_name>/ for later reuse
Backs up the original config and creates a clean template config
Updates the global template registry with file hashes for change detection

Template to Project

Creating a project from a template allows you to quickly start new projects based on proven patterns. This accelerates development and ensures adherence to best practices.

# Create a new project from a template
thothctl project convert --make-project --template-project-type terraform

# For Terragrunt projects
thothctl project convert --make-project --template-project-type terraform-terragrunt

When creating a project from a template, ThothCTL:

Restores the project configuration from the template backup (~/.thothcf/<project_name>/)
Checks for template updates (files that differ from the registry)
Finds all #{placeholder}# expressions in project files
Replaces each placeholder with the corresponding value from [project_properties]
Generates a catalog-info.yaml for Backstage integration

IaC Framework Conversion

ThothCTL supports conversion between different Infrastructure as Code frameworks, allowing you to migrate from one tool to another or use multiple tools together.

Terramate Stacks

Terramate is a tool for managing multiple Terraform stacks. Converting to Terramate stacks allows for more advanced deployment patterns.

# Create Terramate stacks from a Terraform project
thothctl project convert --make-terramate-stacks

# Specify a branch name for Terramate stacks
thothctl project convert --make-terramate-stacks --branch-name feature/terramate-migration

When creating Terramate stacks, ThothCTL:

Analyzes the existing Terraform configuration
Creates appropriate stack structure
Sets up stack dependencies
Configures Terramate-specific features

Project Types

ThothCTL supports different project types to match your organization’s needs:

Terraform

Terraform is a widely used Infrastructure as Code tool for provisioning and managing cloud infrastructure.

# Convert to a Terraform template
thothctl project convert --make-template --template-project-type terraform

# Create a Terraform project from a template
thothctl project convert --make-project --template-project-type terraform

OpenTofu

OpenTofu is an open-source fork of Terraform that provides similar functionality.

# Convert to an OpenTofu template
thothctl project convert --make-template --template-project-type tofu

# Create an OpenTofu project from a template
thothctl project convert --make-project --template-project-type tofu

AWS CDK v2

AWS CDK (Cloud Development Kit) is a framework for defining cloud infrastructure using familiar programming languages.

# Convert to a CDK v2 template
thothctl project convert --make-template --template-project-type cdkv2

# Create a CDK v2 project from a template
thothctl project convert --make-project --template-project-type cdkv2

Terraform with Terragrunt

Terragrunt as an orchestration layer on top of Terraform/OpenTofu.

# Convert to a Terraform+Terragrunt template
thothctl project convert --make-template --template-project-type terraform-terragrunt

# Create a project from a Terraform+Terragrunt template
thothctl project convert --make-project --template-project-type terraform-terragrunt

Standalone Terragrunt

For projects that use Terragrunt as the primary configuration format.

thothctl project convert --make-template --template-project-type terragrunt

Terraform Module

For reusable Terraform module projects.

thothctl project convert --make-template --template-project-type terraform_module

Custom

For any project type not covered by the predefined types.

thothctl project convert --make-template --template-project-type custom

Examples

Converting a Terraform Project to a Template

# Navigate to your Terraform project
cd my-terraform-project

# Convert the project to a template
thothctl project convert --make-template --template-project-type terraform

Creating a New Project from a Template

# Navigate to the directory where you want to create the project
cd projects

# Create a new project from a template
thothctl project convert --make-project --template-project-type terraform

Converting a Terraform Project to Terramate Stacks

# Navigate to your Terraform project
cd my-terraform-project

# Convert to Terramate stacks
thothctl project convert --make-terramate-stacks

Best Practices

Version Control Templates: Store templates in version control to track changes and enable collaboration
Document Templates: Include clear documentation with each template explaining its purpose and usage
Parameterize Appropriately: Identify which values should be customizable in templates
Test Conversions: Always test converted projects or templates to ensure they work as expected
Maintain Consistency: Use consistent naming and structure conventions across templates
Update Regularly: Keep templates updated with the latest best practices and security recommendations

Integration with CI/CD

You can integrate project conversion into your CI/CD pipeline to automate template generation:

# GitHub Actions example for template generation
name: Generate Template

on:
  push:
    branches: [ main ]
    paths:
      - 'templates/**'

jobs:
  generate-template:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          
      - name: Install ThothCTL
        run: pip install thothctl
        
      - name: Convert to Template
        run: |
          cd templates/source-project
          thothctl project convert --make-template --template-project-type terraform
        
      - name: Commit Template
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "chore: Update generated template"
          file_pattern: "templates/generated/*"

This site is open source. Improve this page.