feat: warn when .terraform.lock.hcl is modified during terraform init #18276

blink-so · 2025-06-08T02:20:38Z

This PR adds checksum validation for .terraform.lock.hcl files before and after running terraform init to detect when provider hashes are missing for the target architecture.

Problem

When users run terraform init locally on a different OS/architecture than their Coder instance, the generated .terraform.lock.hcl file may be missing provider hashes for the target architecture. This causes Terraform to download providers unnecessarily during provisioning, slowing down the process.

Solution

Calculate SHA256 checksum of .terraform.lock.hcl before running terraform init
Calculate checksum again after terraform init completes
If checksums differ, log a warning with actionable guidance
Warning appears in both debug and error streams for visibility

Changes

Added calculateFileChecksum() helper function using SHA256
Added getTerraformLockFilePath() helper function
Modified init() function to perform checksum validation
Added comprehensive unit tests
Warning message guides users to regenerate lock file on correct architecture

Testing

Unit tests verify checksum calculation and file path functions
Code compiles successfully
Warning only appears when lock file is actually modified

The warning message provides clear guidance on how to resolve the issue by regenerating the lock file on the same OS/architecture as the Coder instance.

This change addresses issue #18237 by adding checksum validation for .terraform.lock.hcl files before and after running terraform init. When the lock file is modified during init, it indicates that provider hashes may be missing for the target architecture, leading to unnecessary provider downloads and slower provisioning. Changes: - Add calculateFileChecksum() helper function using SHA256 - Add getTerraformLockFilePath() helper function - Modify init() function to calculate checksums before/after terraform init - Log warning when lock file changes with actionable guidance - Add unit tests for new functionality The warning message guides users to regenerate the lock file on the same OS/architecture as their Coder instance to improve performance. Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

Fixes gosec G306 linting error that expects WriteFile permissions to be 0600 or less for security reasons. Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

johnstcn

There's lots of other reasons for modifications to the lock file. The current wording we add could potentially send folks down a rabbit hole.

What if we instead:

Logged the diff of the lock file to provide additional troubleshooting information,
Linked to the official documentation https://developer.hashicorp.com/terraform/language/files/dependency-lock#understanding-lock-file-changes so that folks can figure out the potential reason on their own?

blink-so · 2025-06-09T08:12:55Z

Great feedback @johnstcn! You're absolutely right that there are many reasons for lock file modifications and the current warning could be misleading.

I'll implement your suggestions:

Log the diff: This will provide much more actionable troubleshooting information
Link to official docs: Better to direct users to authoritative documentation rather than making assumptions

This approach will be more helpful and less presumptuous about the cause. Let me update the implementation accordingly.

@johnstcn

Based on review feedback from @johnstcn, this commit improves the terraform lock file change detection by: 1. **Logging actual diff**: Instead of just checksums, now logs the actual differences in the lock file, providing actionable troubleshooting information. 2. **Neutral messaging**: Changed from WARNING to INFO level with neutral language that doesn't assume the cause of changes. 3. **Official documentation**: Links to HashiCorp's official documentation about lock file changes instead of making assumptions about the cause. 4. **Better user experience**: Users get helpful diff output and can understand what changed and why, rather than being sent down a potentially incorrect troubleshooting path. The implementation now: - Saves the original lock file before terraform init - Generates a simple diff showing added/removed lines - Provides informative messaging with official docs link - Includes comprehensive test coverage Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

blink-so · 2025-06-09T08:19:58Z

✅ Implemented the suggested improvements!

I've updated the implementation based on your excellent feedback:

Changes Made

1. Actual Diff Logging 📊

Replaced checksum comparison with actual file diff generation
Shows added/removed lines with +/- prefixes
Provides actionable troubleshooting information

2. Neutral Messaging ℹ️

Changed from WARNING to INFO level
Removed assumptions about the cause
Uses neutral language: "This is normal when Terraform downloads providers or updates dependencies"

3. Official Documentation Link 📚

Links directly to HashiCorp's official docs: https://developer.hashicorp.com/terraform/language/files/dependency-lock#understanding-lock-file-changes
Lets users understand the various reasons for lock file changes

4. Better Implementation 🔧

Saves original lock file before terraform init
Generates simple but informative diff output
Cleans up temporary files automatically
Added comprehensive test coverage for the new diff functionality

Example Output

INFO: .terraform.lock.hcl was modified during 'terraform init'. This is normal when Terraform downloads providers or updates dependencies. See https://developer.hashicorp.com/terraform/language/files/dependency-lock#understanding-lock-file-changes for more information about lock file changes.

Lock file changes:
--- .terraform.lock.hcl (before terraform init)
+++ .terraform.lock.hcl (after terraform init)
- # This file is maintained automatically by "terraform init".
+ # This file is maintained automatically by "terraform init".
+ provider "registry.terraform.io/hashicorp/aws" {
+   version = "5.99.1"
+   hashes = [
+     "h1:abc123...",
+   ]
+ }

This approach is much more helpful and doesn't make assumptions about why the lock file changed. Thanks for the great suggestions! 🙏

johnstcn · 2025-06-09T10:15:29Z

provisioner/terraform/executor.go

+
+	// Copy the lock file if it exists
+	if lockFileData, err := os.ReadFile(lockFilePath); err == nil {
+		_ = os.WriteFile(preInitLockFile, lockFileData, 0644)


This needs to be formatted speficially as octal, e.g.:

- _ = os.WriteFile(preInitLockFile, lockFileData, 0644) + _ = os.WriteFile(preInitLockFile, lockFileData, 0o644)

I don't think we should be writing to the work directory directly. If we need to write a file, we should write to a temporary directory instead. Do we actually need to persist the lock file content pre-init? Can't we just store in memory instead?

If we write a file to disk, we need to ensure we use minimal permissions (0o600) or the gosec linter will complain.

kylecarbs · 2025-06-09T11:51:32Z

There was a bug with this chat. Closing this PR in favor of the new.

blink-so bot and others added 5 commits June 8, 2025 02:20

fix: apply go fmt to executor.go

262c9f2

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

fix: retrigger CI after Go version fix

c16008f

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

fix: use octal notation for file permissions in test

a45984d

Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

fix: use more restrictive file permissions in test (0o600)

b397d1e

Fixes gosec G306 linting error that expects WriteFile permissions to be 0600 or less for security reasons. Co-authored-by: kylecarbs <7122116+kylecarbs@users.noreply.github.com>

johnstcn reviewed Jun 9, 2025

View reviewed changes

blink-so bot mentioned this pull request Jun 9, 2025

feat: warn when .terraform.lock.hcl is modified during terraform init #18280

Closed

kylecarbs closed this Jun 9, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: warn when .terraform.lock.hcl is modified during terraform init #18276

feat: warn when .terraform.lock.hcl is modified during terraform init #18276

blink-so bot commented Jun 8, 2025

Uh oh!

johnstcn left a comment

Uh oh!

blink-so bot commented Jun 9, 2025

Uh oh!

blink-so bot commented Jun 9, 2025

Uh oh!

johnstcn Jun 9, 2025

Uh oh!

kylecarbs commented Jun 9, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

feat: warn when .terraform.lock.hcl is modified during terraform init #18276

feat: warn when .terraform.lock.hcl is modified during terraform init #18276

Conversation

blink-so bot commented Jun 8, 2025

Problem

Solution

Changes

Testing

Uh oh!

johnstcn left a comment

Choose a reason for hiding this comment

Uh oh!

blink-so bot commented Jun 9, 2025

Uh oh!

blink-so bot commented Jun 9, 2025

Changes Made

1. Actual Diff Logging 📊

2. Neutral Messaging ℹ️

3. Official Documentation Link 📚

4. Better Implementation 🔧

Example Output

Uh oh!

johnstcn Jun 9, 2025

Choose a reason for hiding this comment

Uh oh!

kylecarbs commented Jun 9, 2025

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.