CloudBoosterDocs

Import your Terraform stack into CloudBooster

- You need **Organization Admin** or **Project Owner** access in CloudBooster.

Import your Terraform stack into CloudBooster

This guide walks you through importing an existing Terraform-managed infrastructure into CloudBooster using the built-in import wizard. You export your local Terraform state, upload it to CloudBooster, review the proposed resource mappings, and confirm the import so CloudBooster can begin managing everything through GitOps.

This is a hosted-platform (portal) feature, not a CLI command

Importing existing infrastructure happens in the CloudBooster portal. There is no cbx import command, and cbx-cli exposes no state-file import flags. You'll use the Terraform CLI to export state, then upload it through the portal wizard below.

Before you begin

  • You need Organization Admin or Project Owner access in CloudBooster.
  • You need the Terraform CLI installed locally and access to the working directory that contains the state you want to import.
  • The state must be accessible via terraform state pull from your local machine. Remote-state backends (S3, Terraform Cloud, etc.) are not supported by this workflow.
  • Review the cross-account role security model to understand how credentials and state data are handled.

Sensitive data in state files

Terraform state can contain secrets (passwords, tokens, private keys). Before uploading, review tfstate.json for sensitive values. CloudBooster encrypts state data at rest and in transit, but you should still verify that no plaintext secrets are included in the file you upload.

Step 1 — Export Terraform state

Open a terminal in the Terraform working directory you want to import.

  1. Ensure you are in the correct workspace: 
    terraform workspace show
  2. Export the current state to a local JSON file: 
    terraform state pull > tfstate.json
  3. Verify the file was created and contains resources: 
    cat tfstate.json | jq '.resources | length'

The tfstate.json file now contains a snapshot of every resource tracked by Terraform in this workspace.

Export Terraform state

Step 2 — Upload

Open the import wizard from the CloudBooster portal: Projects → Import → Terraform Stack.

  1. Choose the target project (or create a new one).
  2. Select Terraform as the source.
  3. Drag and drop tfstate.json into the upload area, or click Browse to select it.
  4. Click Upload.

The wizard validates the JSON structure, checks for unsupported provider versions, and begins parsing the resource graph. A progress indicator shows the parsing status.

Upload state file

Step 3 — Review

After the upload completes, the Review Dashboard presents every discovered Terraform resource in a searchable, filterable table.

ColumnDescription
ResourceTerraform resource type and name (e.g., aws_instance.web_server)
ProviderTerraform provider that manages this resource
CB MappingThe CloudBooster resource definition that will manage this asset
StatusMapped, Unmapped, or Conflict

You can:

  • Toggle resources in or out of the import set.
  • Override the proposed CB mapping for individual resources.
  • Group by provider, resource type, or module path.
  • Inspect the raw Terraform configuration block for any resource.

Review mapping

Step 4 — Confirm

When you are satisfied with the mapping, click Confirm import.

CloudBooster:

  1. Generates Crossplane Claims for every mapped resource.
  2. Writes the Claims and a Terraform-to-CB mapping manifest to the project's GitOps repository.
  3. Opens a pull request (if GitOps is configured for review) or applies immediately (if auto-apply is enabled).
  4. Creates a project snapshot so the import can be rolled back.

You receive a confirmation summary showing the number of resources under management, the GitOps commit SHA, and an estimated reconciliation time.

Confirm import

Step 5 — Manage

After confirmation, your resources appear in the CloudBooster portal as first-class managed assets.

From the project view you can:

  • Drift detection: CloudBooster continuously compares the live cloud state with the GitOps Claims and surfaces discrepancies. Drift originating from Terraform runs outside CloudBooster is flagged explicitly.
  • Policy enforcement: Apply CB resource policies (e.g., mandatory tagging, encryption requirements).
  • Cost insights: See per-resource cost attribution based on cloud provider billing data.
  • One-click updates: Modify parameters in the portal UI; CloudBooster generates the updated Claim and pushes it through GitOps.

Manage imported resources

Sample Terraform state

The walkthrough above was written against the following reproducible Terraform configuration. You can apply this in a sandbox account to refresh the screenshots without changing the narrative.

Workspace: default Terraform version: ~> 1.9 Providers: hashicorp/aws ~> 5.0

Compute

ResourceTypeDetails
aws_instance.web_servert3.microAmazon Linux 2023, cb-demo-web SG
aws_launch_template.webLaunch templateAMI ami-0abcdef1234567890, user data installs nginx

Networking

ResourceTypeDetails
aws_vpc.mainVPCCIDR 10.0.0.0/16
aws_subnet.public_aSubnetCIDR 10.0.1.0/24, AZ us-east-1a
aws_subnet.public_bSubnetCIDR 10.0.2.0/24, AZ us-east-1b
aws_internet_gateway.mainInternet gatewayAttached to aws_vpc.main
aws_lb.webApplication Load BalancerInternet-facing, HTTP:80

Storage

ResourceTypeDetails
aws_s3_bucket.assetsS3 bucketVersioning enabled, SSE-S3

Database

ResourceTypeDetails
aws_db_instance.mainRDS PostgreSQL 15db.t3.micro, storage encrypted

Security

ResourceTypeDetails
aws_security_group.webSecurity groupIngress 80/443 from 0.0.0.0/0, egress open
aws_security_group.dbSecurity groupIngress 5432 from aws_security_group.web only
aws_iam_role.ec2_roleIAM roleAmazonSSMManagedInstanceCore attached

Tags (applied to all resources)

KeyValue
Projectcb-terraform-demo
Environmentsandbox
ManagedByterraform

What if?

Empty state file

If the upload succeeds but the dashboard shows 0 resources, check the following:

  1. Workspace mismatch: terraform state pull exports the state of the currently selected workspace. Switch to the correct workspace with terraform workspace select <name> and re-export.
  2. Local vs. remote state: This workflow only supports local state files exported via terraform state pull. If your backend is configured to S3, Terraform Cloud, or another remote store, the CLI may still return a local copy, but verify that .terraform/terraform.tfstate or your configured backend is reachable.
  3. State locking: If another process holds the state lock, terraform state pull may fail silently or return stale data. Wait for the lock to release and try again.
  4. Resource exclusion: Some resource types (e.g., data sources, null resources) are skipped by default. Expand the Advanced settings panel in the wizard and enable the relevant resource families if you need them imported.

Upload failure

If the upload fails with an error message, the most common causes are:

  1. Invalid JSON: The file must be a valid Terraform state JSON document (schema version 4). Run terraform state pull > tfstate.json fresh rather than copying .terraform.tfstate directly, which may be in a different format.
  2. File too large: State files over 50 MB are rejected to protect upload performance. If your state is larger, consider splitting the project into smaller workspaces or using the terraform state rm command to exclude heavy resources before export.
  3. Unsupported provider: CloudBooster does not yet support every Terraform provider. The wizard lists unsupported providers in the error detail. Remove those resources from the state or open a support request for provider support.
  4. Network issues: Ensure that api.cloudbooster.io is reachable from your browser and that no corporate proxy blocks multipart uploads.

Ambiguous mappings

Sometimes CloudBooster discovers a Terraform resource but cannot confidently map it to a single CB resource definition. This is shown as Ambiguous in the Status column.

  1. Click the resource row to open the mapping panel. CloudBooster lists the candidate definitions with a confidence score.
  2. Review the schema compatibility: Each candidate shows which parameters can be inferred from the Terraform state and which require manual input.
  3. Pick the best match or select Skip to leave the resource unmanaged.
  4. If none of the candidates fit, you can Request a new definition from the CloudBooster support team. Include the resource address (e.g., aws_instance.web_server) and a brief description of the desired management behavior.

Secrets in state

Terraform state files can contain plaintext secrets. If the wizard detects values that look like passwords, API keys, or private keys, it surfaces a warning before you confirm the import.

  1. Review the flagged values in the security panel.
  2. Rotate any exposed credentials after import is complete. CloudBooster does not store secrets from the state file in GitOps; it replaces them with references to a secrets manager.
  3. Enable encryption at rest in your CloudBooster project settings if you have not already done so.

Next steps

On this page