Skip to content

docs: describe how local_file handles changes made outside of Terraform - #533

Open
fjvbn2003 wants to merge 1 commit into
hashicorp:mainfrom
fjvbn2003:docs-local-file-drift
Open

fjvbn2003 wants to merge 1 commit into
hashicorp:mainfrom
fjvbn2003:docs-local-file-drift

Conversation

@fjvbn2003

Copy link
Copy Markdown

Related Issue

Relates to #262 and #87 (documentation only, does not fix them)

Description

The local_file and local_sensitive_file pages have a "Note about resource behaviour" that covers one case: the file is missing, so Terraform reports the resource as deleted and creates it again.

The same thing happens when the file still exists but its content was changed outside of Terraform. Read compares the SHA1 of the file with the id in the state and calls RemoveResource when they differ (resource_local_file.go, same code in resource_local_sensitive_file.go). As a result:

People who use local_file for files that others may edit (the case in #262) only find this out after their edit is overwritten. This PR adds a second note with these three points to both resources, in the templates and in the generated docs/ pages. The text in docs/ is the same as in the templates, so make generate should give the same result.

How I checked it (OpenTofu v1.9.0, provider hashicorp/local v2.9.1, linux_amd64; the behavior is in the provider's Read, so it should be the same with Terraform, which I did not run):

resource "local_file" "plain" {
  filename = "${path.module}/out/plain.txt"
  content  = "v1\n"
}
resource "local_file" "ignored" {
  filename = "${path.module}/out/ignored.txt"
  content  = "v1\n"
  lifecycle { ignore_changes = [content] }
}
resource "local_file" "perm" {
  filename        = "${path.module}/out/perm.txt"
  content         = "v1\n"
  file_permission = "0644"
}

After apply:

Change made outside of Terraform Result
echo edited >> out/plain.txt, then plan -refresh-only Note: Objects have changed outside of OpenTofu / # local_file.plain has been deleted
same, then plan # local_file.plain will be created, Plan: 1 to add
echo edited >> out/ignored.txt (has ignore_changes = [content]), then plan # local_file.ignored will be created; apply writes v1 back
chmod 0600 out/perm.txt, then plan -detailed-exitcode No changes, exit code 0
local_sensitive_file with ignore_changes = all, content edited has been deleted, then will be created

No changelog entry, since this is a documentation change.

This change was drafted with AI assistance and reviewed by me. The AI tool drafted the note and this description; I ran the commands above and checked the result against the provider source.

Rollback Plan

  • If a change needs to be reverted, we will roll out an update to the code within 7 days.

Changes to Security Controls

Are there any changes to security controls (access controls, encryption, logging) in this pull request? If so, explain.

No. Documentation only.

🤖 Generated with Claude Code

When the content of a file managed by local_file or local_sensitive_file
is changed outside of Terraform, Read compares the SHA1 of the file with
the id in the state and removes the resource from the state. The plan
then shows the resource as deleted and proposes to create it again, so
the next apply overwrites the external change. ignore_changes does not
help, because the resource is planned for creation. Changes to the file
mode are not detected at all.

The docs only mention the case where the file is missing. Add a note
about the content and permission cases to both resources, in the
templates and in the generated pages.

Related: hashicorp#262, hashicorp#87

Assisted-by: Claude Opus 5.5
Signed-off-by: YoungjuKim <[email protected]>
@fjvbn2003
fjvbn2003 requested a review from a team as a code owner October 16, 2026 15:54
@hashicorp-cla-app

hashicorp-cla-app Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@hashicorp-cla-app

Copy link
Copy Markdown

CLA assistant check

Thank you for your submission! We require that all contributors sign our Contributor License Agreement ("CLA") before we can accept the contribution. Read and sign the agreement

Learn more about why HashiCorp requires a CLA and what the CLA includes

Have you signed the CLA already but the status is still pending? Recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant