Adopting Terraform on an Existing Files.com Site

Terraform is sometimes introduced to an already-running Files.com site rather than a new greenfield environment. In these cases, the goal is to bring existing configuration under Terraform management without disrupting production, unintentionally deleting resources, or losing configuration fidelity.

This page explains how to safely apply Terraform on an existing Files.com site, establish an initial state, import existing resources, and adopt Terraform incrementally in production.

Once Terraform is adopted, it becomes the source of truth for the resources it manages. Make changes through Terraform rather than the Files.com UI or API to avoid drift.

Preparing to Use Terraform on an Existing Site

Before running Terraform against a live Files.com site, decide which resources Terraform will manage and plan for importing existing configuration rather than recreating it.

Existing Files.com sites often contain critical resources that cannot be safely deleted or recreated, so Terraform must be introduced carefully and incrementally.

Do not apply Terraform to a production site until imports are complete and Terraform plans have been reviewed to confirm that no unintended changes or deletions are proposed.

Establishing Initial Terraform State

Terraform state represents Terraform’s understanding of the real resources that exist in your Files.com site. For an existing site, this state must be established before any changes are applied.

Store Terraform state in a location scoped to the Files.com site being managed, which is typically a Production site or a specific Child site. Create the state before defining large numbers of resources and treat it as production data, since it determines how Terraform evaluates changes and detects drift.

Never recreate existing Files.com resources through Terraform in order to establish state. Attempting to do so risks duplicating resources or triggering destructive operations.

Importing Existing Files.com Resources

Existing Files.com resources must be imported into Terraform state using terraform import.

Importing associates an existing resource in Files.com with a Terraform resource definition, allowing Terraform to manage it safely going forward without modifying it during the import process.

A typical import workflow begins by defining a Terraform resource block that matches the existing Files.com configuration. The resource is then imported into state, after which terraform plan is run to verify that Terraform proposes no changes. Repeat this process incrementally for each resource type being brought under Terraform management.

Use Terraform to modify a resource only after it has been imported and verified through a no-op plan.

Preventing Unintended Deletions

Many Files.com resource types are dangerous or irreversible to delete, particularly in production environments. Treat Terraform plans that include resource deletions as blocking events that require investigation.

For critical resources, it is strongly recommended to use lifecycle { prevent_destroy = true } to guard against accidental deletion. If Terraform proposes deleting an existing resource, this usually indicates incomplete imports or configuration drift. Resolve this before applying any changes.

Managing Configuration Drift

Once Terraform is adopted, make configuration changes through Terraform rather than through the Files.com UI or API. Manual changes outside Terraform introduce drift, which Terraform may attempt to correct by reverting or deleting resources during the next apply.

Review Terraform plans regularly to detect drift. When drift is detected, the preferred approach is to import or codify the missing configuration rather than suppressing changes. Limit the use of ignore_changes and treat it as a temporary mitigation rather than a long-term solution.

Terraform works best when it is treated as the authoritative system for configuration.

Incremental Adoption in Production

Terraform does not need to manage every Files.com resource immediately. A safe adoption approach starts with a small, low-risk subset of resources and expands gradually as confidence increases.

Import, validate, and stabilize each resource before additional resources are added. Avoid mixing Terraform-managed and manually-managed configuration for the same resource as it makes behavior difficult to reason about and increases the risk of destructive changes.

Incremental adoption allows Terraform to be introduced safely while production systems remain stable.

Recommended Operational Workflow

In production environments, follow a disciplined sequence for Terraform adoption. First, initialize Terraform and establish state, followed by the creation of minimal resource definitions. Import and validate existing resources through Terraform plans that produce no changes.

Add safeguards like prevent_destroy before Terraform is used to make modifications. Do not apply Terraform until the plan shows only expected and intentional changes.