Skip to main content

Import Existing Resources

When you deploy a LiveSystem that references infrastructure already in your cloud account — a VPC built years ago, a Kubernetes cluster managed by another tool, a database created manually — Fractal Cloud detects the existing resource and hands off cleanly instead of failing or creating duplicates. From there you decide whether to leave it alone, adopt it as-is, or reconcile it to your declaration.

This is the same protocol Fractal Cloud uses for break-the-glass. The trigger is the absence of the managed-by: fractal-cloud tag on a resource that the agent has identified as matching one of your declared components.

When to use this​

  • Onboarding existing infrastructure into Fractal Cloud governance for the first time
  • Migrating from Terraform, Pulumi, ARM/Bicep, or a manually-managed environment
  • Referencing infrastructure provisioned by another team or tool that you don't want to take over yet
  • Combining Fractal Cloud with infrastructure that must remain externally managed for compliance or organisational reasons

How identification works​

The agent does not use tags to find resources. It uses the natural identifier for each component type — typically a name combined with a scope (datacenter, region, parent network, etc.) declared in your LiveSystem.

Offer typeNatural identifier
VPC / virtual networkName within region/datacenter
Subnet / VLANName within parent network
Virtual machineName within folder/resource group
Kubernetes clusterName within region
Object storage bucketGlobally unique name
Database instanceName within scope

When you declare a component in your LiveSystem with the same name and scope as an existing resource, the agent finds it and proceeds with the import flow. If you declare with a different name, the agent will create a new resource side-by-side instead.

The import flow​

                ┌──────────────────────────────────┐
                │  You declare a component in your │
                │  LiveSystem with the natural     │
                │  identity of an existing resource │
                └──────────────┬───────────────────┘
                               │
                               v
                ┌──────────────────────────────────┐
                │  Agent reconciles, finds the     │
                │  resource, sees no `managed-by`  │
                │  tag                              │
                └──────────────┬───────────────────┘
                               │
                               v
                ┌──────────────────────────────────┐
                │  Component status:                │
                │  ManualOverride                   │
                │  (label: "Existing Resource Detected") │
                │  Agent reads output fields,       │
                │  reports drift, never modifies    │
                └──────────────┬───────────────────┘
                               │
                       you choose one of:
                               │
                ┌──────────────┼───────────────────┐
                │              │                   │
                v              v                   v
       ┌──────────────┐ ┌────────────┐ ┌────────────────────┐
       │ Manage       │ │ Adopt and  │ │ Adopt as-is        │
       │ Externally   │ │ Reconcile  │ │ (update            │
       │              │ │ to         │ │  declaration       │
       │              │ │ Declaration│ │  first)            │
       └──────────────┘ └────────────┘ └────────────────────┘

Step-by-step​

1. Declare the component in your LiveSystem​

Reference the existing resource by its natural identifier in your declaration. Use the same name (and scope) the resource already has in the cloud. The values for parameters like cidrBlock should match the existing resource — any mismatch becomes a drift report (which you'll resolve in step 4).

The agent matches existing AWS resources by Name tag (or by ID for resources that have one) within the declared region.

// Existing VPC named "prod-vpc" in eu-west-1
const vpc = network.aws.vpc({
  id: 'prod-vpc',
  name: 'prod-vpc',
  region: 'eu-west-1',
  cidrBlock: '10.0.0.0/16',
});

// Existing EKS cluster named "platform-eks"
const eks = compute.aws.eks({
  id: 'platform-eks',
  name: 'platform-eks',
  region: 'eu-west-1',
  vpc: vpc,
});

// Existing RDS instance
const db = storage.aws.rds({
  id: 'orders-db',
  name: 'orders-db',
  engine: 'postgres',
  region: 'eu-west-1',
});

2. Deploy the LiveSystem​

Deploy as you normally would. The agent will reconcile your components on its next cycle.

3. Watch for the "Existing Resource Detected" status​

In the Fractal Cloud dashboard, the component will appear with status ManualOverride and the label Existing Resource Detected. Its output fields populate from the actual cloud resource (resource IDs, ARNs, endpoints, etc.) so dependent components in your LiveSystem can resolve references and continue deploying.

The agent also reports a drift output field showing exactly how the existing resource differs from your declaration:

{
  "status": "ManualOverride",
  "outputFields": {
    "vpcId": "vpc-0abc123def456",
    "cidrBlock": "10.0.0.0/16",
    "drift": {
      "instanceTenancy": {
        "declared": "default",
        "actual": "dedicated"
      }
    }
  }
}

4. Choose an adoption option​

You have three options. Each is reversible.

Option A — Manage Externally​

You want the resource to remain managed outside Fractal Cloud. Dependent components can use its output fields, but the agent will never tag, modify, or delete it.

In the dashboard, click Manage Externally on the component. Status transitions to ExternallyManaged and stays there until you change your mind.

Option B — Adopt and Reconcile to Declaration​

You want Fractal Cloud to take over and bring the resource in line with your declaration. Any drifting parameters will be reconciled to the declared values — this may modify the existing resource.

In the dashboard, review the drift diff, then click Adopt and Reconcile. The control plane uses Force Push to apply the two-tag handshake (managed-by: fractal-cloud plus fractal-cloud: reconcile) to the resource. The agent picks up the tags on its next cycle, reconciles, removes the reconcile tag, and returns the component to Active.

Option C — Adopt As-Is​

You want Fractal Cloud to manage the resource going forward, but the current cloud state is what you want — your declaration is what's wrong. Update your declaration first, then adopt.

  1. Use the drift diff in the dashboard to see exactly what to change.
  2. Update your LiveSystem declaration to match the cloud state.
  3. Re-deploy the LiveSystem so the new declaration reaches the agent.
  4. Click Adopt on the component. With declaration and reality already aligned, the reconcile pass is a no-op — the agent simply tags the resource and transitions to Active.

The agent never writes back into your declaration. Updating the declaration is always your action, supported by the drift diff in the UI.

Caveats​

  • The agent may report drift on parameters Fractal Cloud doesn't yet model. Drift detection only covers parameters defined in the agent's Config record for that component type. If the existing resource has configuration outside that scope, you may need to inspect it manually before adopting.
  • Type mismatches are surfaced as errors. If the resource at the natural identifier exists but is the wrong type (e.g. you declared a Kubernetes cluster but a VM exists at that name), the component stays in ManualOverride with a type-mismatch annotation. Resolve manually.
  • Adopting a resource tagged by another IaC tool (Terraform, Pulumi, etc.) creates a dual-management risk. The control plane will warn you. If both Fractal Cloud and the other tool reconcile drift, they will fight. Pick one.

FAQ​

Q: What if the existing resource has the wrong configuration and I want to keep it that way? A: Use Option C (Adopt As-Is). Update your declaration to match reality, then adopt. The agent reconciles to the new declaration, finds no drift, and the resource is unchanged.

Q: Can I import a resource into multiple LiveSystems at once? A: Yes — but only one LiveSystem can own it. See Sharing Components Across LiveSystems for the ownership rules.

Q: What happens if the existing resource is deleted while in ManualOverride? A: The agent reports Missing on its next poll. You can either redeploy (the agent provisions a fresh resource per the declaration) or remove the component from the LiveSystem.

Q: I imported a resource by mistake. How do I undo it? A: If you only chose Manage Externally, no tags were applied — just remove the component from your LiveSystem. If you adopted it, the resource now carries the managed-by and fractal-cloud-owner tags. You can remove managed-by to re-enter ManualOverride and choose differently from there.