DOCSEARCHbyAlgolia
Submit Docs

Terraformer

repository·master·Indexed 12 days ago

https://github.com/googlecloudplatform/terraformer

A CLI tool for 'reverse Terraform' that generates Terraform configuration files (.tf or .json) and tfstate files from existing cloud and infrastructure resources. It supports providers such as Google Cloud, AWS, and Kubernetes. Note: Terraformer was deprecated and archived as of March 16, 2026.

Tokens
46.6K
Snippets
200
Records
242
Agent score
96%

What's inside Terraformer

  1. What is Terraformer?

    master
    Terraformer is a CLI tool designed to perform 'reverse Terraform'. It generates Terraform configuration files (.tf or .json) and tfstate files based on your existing, already-deployed infrastructure. This allows you to import existing resources into Terraform management.

  2. How Terraformer generates tf/json and tfstate files

    master

    Terraformer follows a specific workflow to transform cloud resources into Terraform configuration and state files:

    1. Resource Discovery: Call the target API (e.g., GCP, AWS) to retrieve a list of resources.
    2. ID Extraction: Iterate over the resources and extract only the unique IDs (mapping fields are not required at this stage).
    3. Read-only Data Retrieval: Call the provider to fetch read-only fields for those IDs.
    4. Infrastructure Generation: Call the infrastructure layer to generate the final .tf/.json and .tfstate files.

  4. Importing Virtual Networks and Subnets in Azure

    master

    When importing azurerm_virtual_network, Terraformer imports the configuration with subnet information stripped to prevent circular dependencies.

    Requirement: To successfully import subnet information, you must explicitly import the azurerm_subnet resource type as well.

  5. How the infrastructure layer processes data

    master

    The infrastructure layer converts raw provider data into Terraform files using these steps:

    1. Refresh: Call the provider using the refresh method to retrieve all necessary data.
    2. Struct Conversion: Convert the refreshed data into a Go struct.
    3. HCL Generation: Generate the HCL files (.tf or .json).
    4. State Generation: Generate the corresponding .tfstate files.

    Note: Resource mapping is handled by the providers and Terraform itself. When a Terraform provider adds new attributes to a resource, Terraformer does not require code changes; you only need to update the Terraform provider on your local machine.

  6. Import Xen Orchestra resources with Terraformer

    master

    Terraformer can import resources from Xen Orchestra using the terraform-provider-xenorchestra. To perform an import, use the import xenorchestra command and specify the resource type with the -r flag.

    Security Warning

    Do not pass credentials directly as command-line arguments, as they may be stored in your bash history. Instead, export them as environment variables before running the command.

    Required Environment Variables

    • XOA_URL: The URL for your Xen Orchestra instance (e.g., ws://your-xenorchestra-domain).
    • XOA_USER: Your Xen Orchestra username.
    • XOA_PASSWORD: Your Xen Orchestra password.

    Supported Resources

    • xenorchestra_acl
    • xenorchestra_resource_set
    # Set credentials safely via environment variables
export XOA_URL=ws://your-xenorchestra-domain
export XOA_USER=username
export XOA_PASSWORD=password

# Import a specific resource type (e.g., acl)
terraformer import xenorchestra -r=acl

  7. Import Heroku apps with Terraformer

    master

    Terraformer uses the terraform-provider-heroku to import Heroku resources. Because Heroku is organized by apps, the importer is designed to capture complete apps along with dependent resources like addons and domains.

    Important: Use App IDs (UUIDs) Apps must be identified by their UUID, not their name. To retrieve an app's ID, use the Heroku CLI:

    heroku apps:info --json --app=<NAME>

    Handling Config Vars Imported apps include settable configuration variables (excluding those from add-ons) as config_vars in the Terraform configuration. Since these may contain secrets, you should manually split them into sensitive_config_vars before running terraform plan or apply to ensure security.

    export HEROKU_API_KEY=<token>

# Import all apps for a specific team
./terraformer import heroku --resources=app --team=<TEAM_NAME>

# Import specific apps using their UUIDs
./terraformer import heroku --resources=app --filter=app=<UUID1>
./terraformer import heroku --resources=app --filter=app=<UUID1>:<UUID2>

# Import with a custom output directory pattern
./terraformer import heroku --resources=app --filter=app=<ID> --path-pattern='{output}/{provider}/<DIRECTORY_NAME>'

# Import all enabled account features
./terraformer import heroku --resources=account_feature

  8. Import Opal resources using terraformer

    master

    To import resources from Opal into Terraform, set your authentication token and run the import command.

    Environment Variables:

    • OPAL_AUTH_TOKEN: Your token from https://app.opal.dev/settings#api.
    • OPAL_BASE_URL: Required if running an on-prem installation (obtain from https://my.opal.com).

    Command Flags:

    • --resources: Specify which resource types to import. Use --resources=* for all or specific types like --resources=owner.
    • --path-pattern: Defines the output directory structure using {output}/{provider}.

    Note: The --filter flag is currently not supported for the Opal provider.

    export OPAL_AUTH_TOKEN=Your_token_from_https://app.opal.dev/settings#api
# For on-prem:
# export OPAL_BASE_URL=Your_url_from_https://my.opal.com

./terraformer import opal --resources=* --path-pattern {output}/{provider}

  9. Migrate and use imported Opal Terraform files

    master

    After running terraformer, your files will be in a generated/ subdirectory.

    If you are using Terraform version >= 0.13, you must perform a state migration to map the provider correctly before you can use the files:

    1. Navigate to the generated directory: cd generated/opal/.
    2. Run the state provider replacement command.
    3. Initialize and plan to verify the configuration.
    $ cd generated/opal/
$ terraform state replace-provider -auto-approve "registry.terraform.io/-/opal" "opalsecurity/opal"
$ terraform init
$ terraform plan

  10. Configure Commercetools environment variables

    master

    Before running terraformer for Commercetools, you must export the required authentication credentials. You can also override the default API and Token URLs if your environment uses non-standard endpoints.

    # Required variables
export CTP_PROJECT_KEY=key
export CTP_CLIENT_ID=foo
export CTP_CLIENT_SECRET=bar
export CTP_CLIENT_SCOPE=scope

# Optional variables (overrides defaults)
export CTP_BASE_URL=base_url # default: https://api.sphere.io
export CTP_TOKEN_URL=token_url # default: https://auth.sphere.io

  11. Import or plan Commercetools resources

    master

    Use the plan command to preview changes or the import command to generate Terraform configuration files for existing Commercetools resources. Use the -r flag to specify the resource type.

    # Only planning
./terraformer plan commercetools -r=types

# Import commercetools types
./terraformer import commercetools -r=types

  12. Import Kubernetes resources with Terraformer

    master

    You can use Terraformer to import existing Kubernetes resources into Terraform configuration files. Use the import command with the kubernetes provider name. You can specify multiple resource types using the --resources flag and narrow down the scope of the import using the --filter flag with the syntax resource_type=name1:name2:name3.

    # Import specific Kubernetes resource types
terraformer import kubernetes --resources=deployments,services,storageclasses

# Import specific resources using filters (e.g., specific deployment names)
terraformer import kubernetes --resources=deployments,services,storageclasses --filter=deployment=name1:name2:name3