Jenkins中Terraform报错：Plugin reinitialization required 排查与解决

问题场景 #

在Jenkins任务中执行Terraform流程，执行步骤及报错如下：

+ terraform --version
Terraform v0.15.5

+ rm -rf .terraform/
+ rm -f .terraform.lock.hcl
+ terraform init -upgrade -reconfigure
Upgrading modules...
...

Initializing the backend...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 3.0"...
- Using hashicorp/aws v3.75.2 from the shared cache directory

...

Terraform has been successfully initialized!

...

+ terraform plan -var-file qa-up.tfvars -out=tfplan
╷
│ Error: Could not load plugin
│ 
│ 
│ Plugin reinitialization required. Please run "terraform init".
│ 
│ Plugins are external binaries that Terraform uses to access and manipulate
│ resources. The configuration provided requires plugins which can't be
│ located,
│ don't satisfy the version constraints, or are otherwise incompatible.
│ 
│ Terraform automatically discovers provider requirements from your
│ configuration, including providers used in child modules. To see the
│ requirements and constraints, run "terraform providers".
│ 
│ failed to instantiate provider "registry.terraform.io/hashicorp/aws" to
│ obtain schema: the cached package for registry.terraform.io/hashicorp/aws
│ 3.75.2 (in .terraform/providers) does not match any of the checksums
│ recorded in the dependency lock file


script returned exit code 1

本地执行terraform providers结果：

$ terraform providers

Providers required by configuration:
.
├── provider[registry.terraform.io/hashicorp/aws]
└── module.elasticache
    └── provider[registry.terraform.io/hashicorp/aws] ~> 3.0

Providers required by state:

provider[registry.terraform.io/hashicorp/aws]

本地使用同版本Terraform（v0.15.5）执行无异常。

原因分析 #

1. Jenkins Agent的Terraform共享缓存目录中，hashicorp/aws 3.75.2的包文件损坏或不完整，导致校验和与terraform init生成的.terraform.lock.hcl文件记录的不一致。
2. terraform init -upgrade优先调用了共享缓存中的旧包，该包的校验和与当前配置要求不匹配，即便删除了本地.terraform和锁文件也无法解决。
3. Jenkins Agent与本地环境系统架构不同（如本地为macOS、Jenkins为Linux），缓存的provider包对应其他架构，导致校验和不匹配。

解决方法 #

• 清理共享缓存并重新下载：找到Jenkins Agent上Terraform的共享缓存路径（通常为~/.terraform.d/plugins或系统级路径），删除registry.terraform.io/hashicorp/aws/3.75.2对应的目录，重新执行任务。
• 禁用共享缓存：修改terraform init命令为terraform init -upgrade -reconfigure -plugin-cache=false，强制Terraform将provider下载到当前目录的.terraform/providers下，避免使用共享缓存的损坏包。
• 强制重新获取插件：在terraform init中添加-get-plugins=true参数，确保Terraform重新下载符合校验和要求的provider包。
• 检查Agent权限：确认Jenkins Agent的运行用户对.terraform目录和共享缓存目录有读写权限，避免下载的provider包因权限问题写入不完整。

内容的提问来源于stack exchange，提问作者Roman Newaza