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¶

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:

1. Reads [project_properties] from .thothcf.toml to identify values to parameterize
2. Replaces those values with #{placeholder}# expressions in all project files (.tf, .hcl, .tfvars, etc.)
3. Saves the template to ~/.thothcf/<project_name>/ for later reuse
4. Backs up the original config and creates a clean template config
5. 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:

1. Restores the project configuration from the template backup (~/.thothcf/<project_name>/)
2. Checks for template updates (files that differ from the registry)
3. Finds all #{placeholder}# expressions in project files
4. Replaces each placeholder with the corresponding value from [project_properties]
5. 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:

1. Analyzes the existing Terraform configuration
2. Creates appropriate stack structure
3. Sets up stack dependencies
4. 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¶

1. Version Control Templates: Store templates in version control to track changes and enable collaboration
2. Document Templates: Include clear documentation with each template explaining its purpose and usage
3. Parameterize Appropriately: Identify which values should be customizable in templates
4. Test Conversions: Always test converted projects or templates to ensure they work as expected
5. Maintain Consistency: Use consistent naming and structure conventions across templates
6. 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/*"