CloudBoosterDocs

Import an existing Pulumi stack into CloudBooster

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

Import an existing Pulumi stack into CloudBooster

This guide walks you through importing an existing Pulumi stack into CloudBooster by uploading its state file. CloudBooster parses the state, maps every resource to the closest CloudBooster definition, and lets you review and confirm the mapping before it begins 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 Pulumi 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 Pulumi CLI installed and authenticated against the backend that stores your stack's state (Pulumi Cloud, S3, Azure Blob, GCS, or a self-hosted backend).
  • You need access to the Pulumi stack you want to import.
  • Review What is stripped from the state file? to understand exactly what data CloudBooster removes before storage.
  • Review Encryption at rest for how the persisted resource graph is protected after upload.

Step 1 — Export your Pulumi state

Navigate to the project directory that contains the Pulumi stack you want to import, then export the state to a local JSON file:

pulumi stack export > state.json

Offline backends

If your stack uses a self-managed backend (e.g., S3, Azure Blob, GCS), ensure you are authenticated to that backend before running pulumi stack export. The CLI must be able to read the state object just as it would during a normal pulumi up.

Secrets in state files

Pulumi state files may contain encrypted secrets. CloudBooster strips all secret values during upload (see What is stripped from the state file? below). Do not decrypt secrets before export.

Step 2 — Upload to CloudBooster

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

  1. Choose the target project (or create a new one).
  2. Select Pulumi as the provider.
  3. Click Upload state file and select the state.json you exported in Step 1.
  4. CloudBooster validates the file format, version, and size. If validation passes, click Proceed to review.

Upload limits

The maximum accepted file size is 50 MB. If your state file exceeds this limit, see the What if? section below for workarounds.

Step 3 — Review dashboard

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

ColumnDescription
ResourcePulumi resource type and logical name
ProviderCloud provider that hosts the resource (e.g., AWS, Azure, GCP)
CB MappingThe CloudBooster resource definition that will manage this asset
StatusMapped, Unmapped, Conflict, or Ambiguous

You can:

  • Toggle resources in or out of the import set.
  • Override the proposed CB mapping for individual resources.
  • Group by provider, resource family, or Pulumi stack output.

Multi-provider stacks

Pulumi stacks often span multiple cloud providers. CloudBooster groups resources by provider automatically. Resources from providers that are not yet supported by CloudBooster will show as Unmapped.

Step 4 — Confirm import

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

CloudBooster:

  1. Generates Crossplane Claims for every mapped resource.
  2. Writes the Claims 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.

What is stripped from the state file?

CloudBooster never stores raw Pulumi state files. During upload the following fields are removed before the resource graph is persisted:

FieldReason
secrets_providerPrevents leakage of the encryption provider configuration.
deployment.secretsAll secret values are stripped regardless of encryption state.
provider.credentialsCloud provider access keys and session tokens are removed.
resource.urn (internal)Internal Pulumi URNs that reference the source backend are discarded.

The remaining resource graph (types, IDs, parent-child relationships, and non-sensitive inputs/outputs) is retained so CloudBooster can generate accurate Crossplane Claims.

Encryption at rest

After the state file is uploaded and stripped, the remaining resource graph is encrypted at rest before being persisted in CloudBooster's backend storage.

AspectDetail
AlgorithmAES-256-GCM
Key rotationAutomatic, every 90 days
Key storageHardware security module (HSM) backed
ScopePer-project encryption envelope

CloudBooster manages encryption keys automatically. Keys are never exposed to project members or stored alongside the data they protect.

What if?

Invalid state file format

If the upload fails with an Invalid format error, check the following:

  1. Pulumi version: CloudBooster expects state file version 3 or later. Run pulumi version to verify your CLI is up to date, then re-export.
  2. Corrupted export: Ensure the pulumi stack export command completed successfully and the file contains valid JSON. You can validate it locally with python -m json.tool state.json.
  3. Backend mismatch: If your stack uses a passphrase-protected local backend, make sure you exported while the passphrase was cached in your environment.

File too large

If the state file exceeds the 50 MB upload limit:

  1. Remove unused resources: Clean up retired resources from your Pulumi stack before exporting. Resources that have been deleted from the stack but linger in state history can bloat the file.
  2. Split the stack: Consider breaking a monolithic stack into smaller logical stacks (e.g., networking, compute, data) and import each separately.
  3. Contact support: If your state legitimately exceeds 50 MB, reach out to CloudBooster support to arrange a secure direct transfer.

Version mismatch

If CloudBooster reports that the state file version is unsupported:

  1. Upgrade your Pulumi CLI to the latest stable release.
  2. Run pulumi stack export --version 3 > state.json to force a modern version.
  3. Re-upload the exported file.

Ambiguous mappings

Sometimes CloudBooster discovers a 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 live resource 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 URN and a brief description of the desired management behavior.

Next steps

On this page