ThothCTL Space Management¶

Overview¶

ThothCTL's space management functionality allows you to organize projects within logical spaces. Each space can have its own configuration for version control systems, Terraform registries, and orchestration tools. This helps maintain consistency across related projects and simplifies credential management.

Use Cases¶

Project Organization: Group related projects within logical spaces
Consistent Configuration: Ensure all projects in a space use the same tools and settings
Credential Management: Centralize credentials for version control, Terraform, and other tools
Environment Separation: Create separate spaces for development, staging, and production
Team Workspaces: Create spaces for different teams or departments

Commands¶

Initialize a Space¶

Usage: thothctl init space [OPTIONS]

  Initialize a new space

Options:
  -s, --space-name TEXT         Name of the space  [required]
  -d, --description TEXT        Description of the space
  -vcs, --vcs-provider [azure_repos|github|gitlab]
                                Version Control System provider  [default:
                                azure_repos]
  -tr, --terraform-registry TEXT
                                Terraform registry URL  [default:
                                https://registry.terraform.io]
  -ta, --terraform-auth [none|token|env_var]
                                Terraform registry authentication method
                                [default: none]
  -ot, --orchestration-tool [terragrunt|terramate|none]
                                Default orchestration tool for the space
                                [default: terragrunt]
  --help                        Show this message and exit.

Remove a Space¶

Usage: thothctl remove space [OPTIONS]

  Remove a space and optionally its associated projects

Options:
  -s, --space-name TEXT  Name of the space to remove  [required]
  -rp, --remove-projects  Remove all projects associated with this space
  --help                 Show this message and exit.

List Spaces¶

Usage: thothctl list spaces

  List all spaces managed by thothctl

Show Space Configuration¶

Usage: thothctl space show SPACE_NAME

  Show space configuration summary

Update Space Configuration¶

Usage: thothctl space update SPACE_NAME [OPTIONS]

  Update an existing space's configuration

Options:
  -d, --description TEXT          New description for the space
  -vcs, --vcs-provider [azure_repos|github|gitlab]
  -ot, --orchestration-tool [terragrunt|terramate|none]
  -tr, --terraform-registry TEXT  Terraform registry URL
  -pr, --policy-repo TEXT         Git URL or path for IaC policies

Activate a Space¶

Usage: thothctl space activate SPACE_NAME

  Set a space as the active context

List Projects with Space Information¶

Usage: thothctl list projects [OPTIONS]

  List all projects managed by thothctl

Options:
  -s, --show-space  Show space information for each project  [default: True]

Basic Usage¶

Creating a Space¶

thothctl init space --space-name development --description "Development environment" --vcs-provider github --terraform-auth token --orchestration-tool terragrunt

This creates a new space named "development" with GitHub as the VCS provider, token-based Terraform registry authentication, and Terragrunt as the orchestration tool.

Creating a Project in a Space¶

thothctl init project --project-name my_project --space development

This creates a new project named "my_project" in the "development" space, inheriting all the space's configurations.

Listing Spaces¶

thothctl list spaces

This displays a list of all spaces with their project counts.

Showing Space Configuration¶

thothctl space show platform-team

This displays a full summary of the space including VCS provider, Terraform registry, orchestration tool, governance policies, associated projects, and credentials status.

Listing Projects with Space Information¶

thothctl list projects

This displays a list of all projects with their associated spaces.

Removing a Space¶

thothctl remove space --space-name development

This removes the "development" space but keeps its projects (they will no longer be associated with any space).

Removing a Space and Its Projects¶

thothctl remove space --space-name development --remove-projects

This removes the "development" space and all projects associated with it.

Space Structure¶

Each space has the following directory structure:

~/.thothcf/spaces/<space_name>/
├── space.toml              # Space configuration file
├── credentials/            # Credentials for various services
├── configs/                # General configurations
├── templates/              # Project templates
├── vcs/                    # Version control system configurations
│   └── <provider>.toml     # Provider-specific configuration
├── terraform/              # Terraform registry configurations
│   └── registry.toml       # Registry configuration
└── orchestration/          # Orchestration tool configurations
    └── <tool>.toml         # Tool-specific configuration

Configuration Files¶

space.toml¶

The main space configuration file:

[space]
name = "development"
version = "1.0.0"

[credentials]
path = "credentials"

[configurations]
path = "configs"

[templates]
path = "templates"

[version_control]
path = "vcs"
default_provider = "github"
providers = ["azure_repos", "github", "gitlab"]

[terraform]
path = "terraform"
registry_url = "https://registry.terraform.io"
auth_method = "token"

[orchestration]
path = "orchestration"
default_tool = "terragrunt"
tools = ["terragrunt", "terramate", "none"]

VCS Configuration¶

Example GitHub configuration (vcs/github.toml):

[provider]
provider = "github"

[settings]
organization = ""
project = ""
repository = ""
branch = "main"
auth_method = "pat"  # Options: pat, oauth, ssh

Terraform Configuration¶

Example Terraform registry configuration (terraform/registry.toml):

[registry]
url = "https://registry.terraform.io"
auth_method = "token"
token_env_var = ""
token = ""

[providers]
[providers.aws]
version = "~> 4.0"
source = "hashicorp/aws"

[providers.azure]
version = "~> 3.0"
source = "hashicorp/azurerm"

Orchestration Configuration¶

Example Terragrunt configuration (orchestration/terragrunt.toml):

[terragrunt]
version = "latest"

[terragrunt.remote_state]
backend = "s3"

[terragrunt.remote_state.config]
bucket = ""
key = "${path_relative_to_include()}/terraform.tfstate"
region = "us-east-1"
encrypt = true

[terragrunt.generate]
provider = true
backend = true

Best Practices¶

Logical Grouping: Create spaces based on logical groupings (environments, teams, products)
Consistent Naming: Use consistent naming conventions for spaces
Documentation: Include descriptive information for each space
Version Control: Use the same VCS provider for all projects in a space
Credential Management: Store credentials securely and reference them in space configurations

Examples¶

Development Space¶

thothctl init space \
  --space-name development \
  --description "Development environment" \
  --vcs-provider github \
  --terraform-auth token \
  --orchestration-tool terragrunt

Production Space¶

thothctl init space \
  --space-name production \
  --description "Production environment" \
  --vcs-provider azure_repos \
  --terraform-auth env_var \
  --orchestration-tool terragrunt

Team Space¶

thothctl init space \
  --space-name data-team \
  --description "Data Engineering Team" \
  --vcs-provider gitlab \
  --terraform-auth token \
  --orchestration-tool terramate

Troubleshooting¶

Common Issues¶

Space Already Exists: Ensure you're not trying to create a space that already exists
Missing Space: Ensure the space exists when creating a project in it
Permission Issues: Check permissions for the .thothcf directory
Configuration Errors: Verify that space configuration files are valid

Debugging¶

For more detailed logs, run ThothCTL with the --debug flag:

thothctl --debug init space --space-name development