Terraform Best Practices

Use Terraform to manage durable Files.com configuration through reviewed code. A change to the configuration can leave an existing setting untouched, update a resource, or delete it. Establish which resources and settings Terraform owns before applying changes to accounts, permissions, folders, or integrations that people and business systems depend on.

Assign One Configuration Authority

For each managed setting, make routine changes through Terraform. The web interface, API, CLI, SCIM, and other provisioning tools can change some of the same objects. A later Terraform plan may detect changes to configured arguments and propose reverting them to match the configuration.

For example, let the identity provider own SCIM-managed users and groups instead of also trying to manage their lifecycle through Terraform. A CLI script can upload files into Terraform-managed folders without taking over management of the folder configuration.

When an emergency requires a manual change, reconcile the code and live resource before the next apply. Do not assume two tools cannot conflict simply because one is called an operational tool.

Group membership also has several configuration paths: a user's group list, a group's user list, and individual membership resources. Choose one way to own each membership relationship. Managing the same relationship through competing lists or resources can cause one change to undo another.

Use ignore_changes only for settings deliberately owned elsewhere. It suppresses updates to those settings; it does not protect the resource from deletion. Ignoring access settings can leave access in place even when the code appears to remove it.

Configured and Omitted Settings

The Files.com provider manages optional arguments that are written in the resource's configuration. Leaving an optional argument out of an existing resource, or removing it, preserves the site's current value. Omission is not an instruction to reset the setting, and subsequent plans show no change for it until the argument is configured again.

For access settings, write the intended value explicitly. These edits have different consequences for an existing files_user resource:

A plan with no changes does not establish that every access setting matches your policy. Check which arguments are actually declared and whether any are ignored. After a folder permission change, use Check Access to verify the intended user's effective access. Removing one grant does not remove access supplied by another direct, Group, or inherited grant.

Import Existing Resources

Follow Adopting Terraform on an Existing Files.com Site to bring existing resources under management. Write matching configuration, import incrementally, and review the plan until it proposes only the changes you intend.

Terraform state records the association between configuration and live objects. Do not edit its JSON by hand to make routine configuration changes. Use configuration files and the supported import or state commands for their intended purposes.

Import each live object into one resource address in one state. Managing the same Files.com object from two states gives two configurations control of its updates and deletion. When another configuration only needs to reference an existing object, use a provider data source where available instead of taking over its lifecycle.

Resource Identity and Deletion

Terraform identifies a managed resource by its configuration address, including its resource label, module path, and any for_each key or count index. Renaming a label, moving a resource into a module, or changing an iteration key can produce a deletion and a new resource instead of a rename. Use Terraform's resource-move mechanisms to preserve the association when reorganizing configuration.

Use stable client identifiers as for_each keys. A client's display name can change without the relationship ending. With count, removing an entry from the middle of an input list shifts the indices of later entries; inspect the resulting updates and replacements. Terraform Loop Iteration illustrates how one client input controls several accounts, folders, Groups, and permissions.

For critical resources, prevent_destroy rejects plans that would delete or replace them while the lifecycle rule remains in the configuration. Removing the entire resource block also removes this protection. Review every deletion and replacement, including those caused by removing a client from an input collection. Recreating a Files.com folder at the same path does not restore its contents or previous permissions.

To hand a resource back to another tool or administrator while keeping it on Files.com, remove it from Terraform management without destroying it. A removed block must include lifecycle { destroy = false } for that outcome. Removing an entry from state while leaving its resource block configured instead makes Terraform plan to create it again.

Protect State and Credentials

Use a backend with appropriate access control and a recoverable history. Configure state locking where the backend supports it, and prevent concurrent applies. Locking support and setup vary by backend; remote storage alone does not establish that it is enabled.

Supply the Files.com API key through a protected environment or secret-management mechanism. State and saved plans can contain sensitive values even when variables are marked sensitive. Protect those artifacts and keep them out of ordinary source-control commits and logs.

The sensitive marker hides values in ordinary output; it does not encrypt them or keep them out of state and saved plans. Use supported ephemeral values or write-only arguments when the Terraform and provider versions allow them, and protect the artifacts even when a particular credential is not retained.

State backups help recover Terraform's records. Restoring an old state file does not undo changes to live Files.com resources or recover deleted file contents.

Separate Environments

Keep production and test configuration values, credentials, and state distinct. A test Workspace can isolate the resources for a limited experiment. Use a Child Site when testing requires independent site settings. Account Structure & Environments covers that choice.

Check the provider endpoint and Remote Server destinations before applying. An environment labeled “test” can still carry production credentials or point at a production folder.

A Terraform workspace separates state. It does not create a Files.com Workspace or Child Site, or change the provider's endpoint and API key automatically. Each environment needs the correct connection values and Files.com resource scope as well as its own state.

Terraform-Managed File Contents

The files_file resource uploads a local file. Changing the local file's contents without changing its source path does not by itself trigger another upload. Set md5 from the source file when Terraform must track those content changes:

resource "files_file" "partner_template" {
  path   = "partner-template.csv"
  source = "${path.module}/partner-template.csv"
  md5    = filemd5("${path.module}/partner-template.csv")
}

A checksum change plans a replacement. Reserve Terraform ownership for files whose contents should be controlled by that configuration. For files that people or business systems continually update, use Files.com's transfer tools or workflows; Terraform can manage their folder and access configuration separately.

Review and Apply Small Changes

Run terraform fmt and terraform validate, then review terraform plan for the intended environment. Inspect deletions, replacements, permission changes, and shared dependencies. Syntax validation does not prove that the resulting users can transfer files or that a workflow's destination is correct.

Keep provider version constraints and the dependency lock file in version control. Review provider upgrades as changes to the configuration workflow, with a fresh plan and behavior checks.

Apply a focused change in the test environment and verify the resulting behavior. Review the production plan with production values before applying it. Reuse modules where they clarify a repeated configuration, while keeping consequential environment differences visible.

Applying without a saved plan generates a new plan; it does not automatically use the plan reviewed earlier. When applying a saved plan, ensure it is the artifact reviewed for that environment. A targeted plan or apply can omit other changes, so review a full plan before considering the configuration reconciled.

An apply that returns an error can leave earlier operations completed. Terraform does not roll them back automatically. Inspect the live resources and updated state, resolve the failure, and review a fresh plan before continuing. Reverting configuration can be part of recovery, but it does not reverse files already delivered or deleted. Include those effects in Production Validation & Change Control.