Terracognita Documentation

Terracognita can import infrastructure directly into Terraform Modules. Use the --module {module/path/name} flag to specify the destination.

Module Structure

When using --module test, the output will aggregate resources into files based on their category (e.g., ec2.tf, s3.tf, iam.tf) inside a module-test directory, with a module.tf file at the root to call the module.

Controlling Variables

By default, Terracognita converts most attributes into variables. To limit which attributes are turned into variables, use the --module-variables <path/to/file> flag. The file must be in JSON or YAML format.

Example JSON configuration:

{
  "aws_instance": [
    "instance_type",
    "cpu_threads_per_core",
    "cpu_core_count"
  ]
}

Example YAML configuration:

aws_instance:
  - instance_type
  - cpu_threads_per_core
  - cpu_core_count

The update.sh script performs two primary types of updates depending on the target:

update_terraform_provider

Used when updating a Terraform provider:

1. Git clones the Cycloid Provider fork repository.
2. Updates the code from the official remote upstream.
3. Creates a Cycloid branch matching the release version.
4. Moves code out of the internal directory.
5. Updates Go imports to match the new path.
6. Applies specific code_fix_* scripts if required.
7. Pushes the new commit and tags.

update_terracognita

Used when updating the Terracognita core:

1. Updates the Terracognita Go module with the latest version.
2. Updates README.md.
3. Applies specific terracognita_fix_* scripts if required.
4. Updates the specific version on the provider package.

After importing your infrastructure with Terracognita, you can verify the generated code by running standard Terraform commands in the same directory:

terraform init
terraform plan -var access_key=$AWS_ACCESS_KEY_ID -var secret_key=$AWS_SECRET_ACCESS_KEY -var region=$AWS_DEFAULT_REGION

To build and install Terracognita from the latest source code, you need Go 1.17+ installed. Use the provided Makefile to install:

git clone https://github.com/cycloidio/terracognita
cd terracognita
make install

To install the latest Linux AMD64 binary, download the tarball, extract it, and move it to your local bin directory.

curl -L https://github.com/cycloidio/terracognita/releases/latest/download/terracognita-linux-amd64.tar.gz -o terracognita-linux-amd64.tar.gz
tar -xf terracognita-linux-amd64.tar.gz
chmod u+x terracognita-linux-amd64
sudo mv terracognita-linux-amd64 /usr/local/bin/terracognita

You can run Terracognita using the official Docker image cycloid/terracognita.

To build your own local image, run:

make dbuild

Docker Execution Example

To run an AWS import and save the output to a local directory, export your cloud credentials and run:

export AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX
export AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export AWS_DEFAULT_REGION=xx-yyyy-0

docker run \
	-v "${PWD}"/outputs:/app/outputs \
	cycloid/terracognita aws \
	--hcl app/outputs/resources.tf

The basic command structure for Terracognita is:

terracognita [TERRAFORM_PROVIDER] [--flags]

Replace [TERRAFORM_PROVIDER] with the provider you want to import (e.g., aws, gcp, azurerm, or vsphere).

General Flags

• --hcl <path>: Specifies the output file for the generated HCL configuration.
• --module <path/name>: Specifies the path where a Terraform module will be generated.
• --tfstate <path>: Specifies the output path for the generated Terraform State.
• --include <resource_name>: Includes specific resources by their Terraform name (e.g., aws_instance).
• --exclude <resource_name>: Excludes specific resources by their Terraform name.

Use terracognita --help for general options or terracognita [PROVIDER] --help for provider-specific flags.

If you are using macOS and have Homebrew installed, you can install Terracognita using the following command:

brew install terracognita

The update.sh script is used to automate the process of updating Terraform and Terraform providers used by Terracognita. It is typically invoked via the command make update-terraform-provider.

To use the script directly, provide the name of the provider as the first parameter. You can also specify a specific version by setting the TAG environment variable.

Terracognita is available in the Arch User Repository (AUR) via two packages:

• terracognita: Targets the latest stable release.
• terracognita-git: Targets the latest git commit.

You can use yay to search and install them:

yay -Ss terracognita

Terracognita is a CLI tool that reads from cloud providers and generates Terraform configuration (HCL) and/or TFState files. It supports multiple providers including AWS, Google Cloud, Azure, and vSphere.

All flags can be provided via command-line arguments or environment variables (e.g., --aws-access-key can be set via AWS_ACCESS_KEY).

To use the tool, you must specify at least one output destination: --module, --hcl, or --tfstate.

Control how the HCL code is structured using these flags:

• --interpolate (default: true): Activates interpolation for the HCL and dependency building for the State file.
• --hcl-provider-block (default: true): Determines whether to generate the provider {} block for the imported provider in the output.