Skip to main content

Adopting Existing Resources

Bringing an existing Files.com Site into your Terraform or OpenTofu configuration requires importing the resources that people and business systems already use. Associate those live users, permissions, folders, and integrations with their resource definitions and state before applying changes. Import preserves the existing object; recreating it can duplicate accounts or remove working configuration and files.

Choose a small set of resources to bring under management first. Decide which process will own each resource and setting, including any users or Groups already maintained by an identity provider. The provider connection must point at the intended Site with the required administrative access.

State and Resource Identity

State records the association between a resource address in configuration and the object on Files.com. Store it in a protected location scoped to the environment being managed, typically a production Site or a particular Child Site. Establish the backend and its locking arrangement before several administrators or pipelines can make changes.

Import each live object into one resource address in one state. Giving two configurations authority over the same object lets either update or delete it. Use a provider data source where available when another configuration only needs to refer to that object.

Import and Compare

Write a resource definition that matches the existing object, then import it using the identifier format in that resource's provider reference. For example, an existing Group named Finance can be declared as:

resource "files_group" "finance" {
  name = "Finance"
}

If its actual Group ID is 123, import it with the command for your tool:

terraform import files_group.finance 123

tofu import files_group.finance 123

These are alternative commands for the same operation. Use the real Group ID from the Site, and review the plan immediately afterward. Repeat the import-and-compare process incrementally for the other resources and their relationships.

A plan with no changes confirms that the declared arguments do not require updates. It does not establish that every setting matches your intended policy. Optional arguments omitted from an existing resource preserve its current Files.com values. Include explicit values for settings the configuration should enforce, especially access settings; Configured and Omitted Settings explains the distinction.

Before the first apply, complete imports for the resources that configuration will manage and resolve every unintended update, deletion, or replacement. Start making deliberate configuration changes only after the imported arrangement is understood.

Ownership After Adoption

Make routine changes to managed settings through configuration. A manual change in the web interface, CLI, or API can produce drift, and the next plan can propose reverting it. Reconcile necessary manual changes with the configuration before applying again. Use ignore_changes only for settings deliberately owned elsewhere, with the consequences described in Configuration Lifecycle.

Review resource deletions and replacements before applying. For critical resources, prevent_destroy rejects them while its lifecycle rule remains in configuration. Removing the whole resource block also removes that protection. Renaming a resource label or changing an iteration key can also break its association with the existing object; preserve that identity through the tool's supported resource-move mechanisms.

Expand management gradually after the first resources are imported and verified. Verify effective user access and the behavior of configured workflows as well as the plan. A state backup recovers the tool's records; restoring it does not undo live changes or recover deleted file contents.