Tình huống xảy ra
Tôi đang dọn dẹp một repo Terraform — gộp các provider vào một root module duy nhất, xóa block provider trùng lặp khỏi child module. Config trông có vẻ ổn. Rồi tôi chạy terraform plan và nhận được lỗi này:
Error: Provider configuration not present
To work with aws_s3_bucket.my_bucket its original provider configuration
at module.storage.provider["registry.terraform.io/hashicorp/aws"] is
required, but it has been removed. This occurs when a provider
configuration is removed while objects created by that provider
still exist in the state.
State vẫn còn chứa các resource gắn với một đường dẫn provider không còn tồn tại trong code nữa. Không có config đó, Terraform không biết phải dùng credentials hay region nào — vì vậy nó từ chối thực thi bất cứ thứ gì.
Tại sao lỗi này xảy ra
Mỗi resource trong terraform.tfstate được liên kết với một địa chỉ provider config cụ thể — không chỉ là loại provider, mà là đường dẫn chính xác bao gồm cả phạm vi module và alias. Xóa đường dẫn đó đi, tham chiếu trong state sẽ bị gãy.
Các nguyên nhân thường gặp:
- Xóa block
providerkhỏi một module - Xóa hoặc đổi tên một module đang có provider config riêng
- Bỏ provider alias (ví dụ:
provider "aws" { alias = "us-east" }) - Di chuyển resource giữa các module mà không cập nhật state cho khớp
Terraform sẽ không tự đoán. Nếu state trỏ tới module.storage.provider["registry.terraform.io/hashicorp/aws"] mà địa chỉ đó không tồn tại trong file .tf của bạn, nó sẽ báo lỗi ngay lập tức — trước khi đánh giá bất cứ thứ gì khác.
Debug: tìm resource bị mồ côi
Bắt đầu bằng cách liệt kê tất cả những gì đang có trong state:
terraform state list
Sau đó kiểm tra một resource cụ thể:
terraform state show module.storage.aws_s3_bucket.my_bucket
Xem trường provider trong kết quả xuất ra. Nó sẽ hiển thị thứ gì đó như module.storage.provider["registry.terraform.io/hashicorp/aws"]. Đường dẫn đó phải tồn tại trong config của bạn — hoặc resource cần được liên kết lại với một provider đang tồn tại.
Để quét nhanh toàn bộ tham chiếu provider trong state:
cat terraform.tfstate | grep '"provider"'
Cách này nhanh hơn việc kiểm tra từng resource một, đặc biệt khi cả một module bị xóa và bạn đang đối mặt với 20+ resource bị mồ côi.
Cách sửa 1 — Tạm thời khôi phục lại block provider
Cách nhanh nhất để gỡ bế tắc: thêm lại config provider còn thiếu đúng như nó vốn có.
# Trong module/storage/main.tf — khôi phục những gì đã bị xóa
provider "aws" {
region = var.aws_region
}
Chạy terraform init && terraform plan. Nếu plan không hiển thị thay đổi nào bất ngờ, bạn đã gỡ được bế tắc. Từ đây bạn có thể thực hiện migration đúng cách thay vì vá víu.
Đây không phải là giải pháp lâu dài — đây là cách rollback an toàn để bạn có thời gian thực hiện migration đúng chuẩn.
Cách sửa 2 — Di chuyển resource trong state sang provider mới
Đang refactor provider config lên root module? Dùng terraform state replace-provider. Lệnh này liên kết lại resource với địa chỉ provider mới mà không động chạm gì đến hạ tầng thực tế:
terraform state replace-provider \
"module.storage.registry.terraform.io/hashicorp/aws" \
"registry.terraform.io/hashicorp/aws"
Resource giờ trỏ tới AWS provider ở cấp root. Không có gì thay đổi trên AWS — chỉ có file state được cập nhật.
Xác nhận lại sau khi sửa:
terraform state show module.storage.aws_s3_bucket.my_bucket
# trường provider giờ phải hiển thị đường dẫn provider ở cấp root
Phần lớn kỹ sư không biết lệnh này tồn tại cho đến khi gặp đúng lỗi này. Đây là lựa chọn gọn gàng nhất khi bạn đang tổ chức lại vị trí provider.
Cách sửa 3 — Di chuyển địa chỉ resource trong state
Nếu bạn đã di chuyển chính resource đó (không chỉ provider của nó), bạn cần cập nhật luôn địa chỉ đầy đủ trong state:
terraform state mv \
module.storage.aws_s3_bucket.my_bucket \
aws_s3_bucket.my_bucket
Lệnh này báo cho Terraform biết: cùng một S3 bucket thực tế đó giờ được theo dõi tại địa chỉ mới này dưới provider cấp root.
# Xác nhận việc di chuyển thành công
terraform state list | grep s3
terraform plan # nên hiển thị không có thay đổi nếu config khớp với thực tế
Cách sửa 4 — Xóa resource khỏi state
Đôi khi câu trả lời đúng là đơn giản là ngừng theo dõi nó. Nếu resource đã bị xóa, hoặc bạn định xóa thủ công, hãy xóa nó khỏi state:
terraform state rm module.storage.aws_s3_bucket.my_bucket
Terraform quên đi resource đó. Nó sẽ không cố xóa resource — nó đơn giản là ngừng quản lý nó. Hữu ích khi bạn đang gỡ bỏ hạ tầng đã được dọn dẹp bên ngoài Terraform.
Xử lý khi có nhiều resource bị ảnh hưởng
Xóa cả một module và giờ 30 resource bị mồ côi? Xử lý hàng loạt:
# Xem tất cả những gì nằm dưới đường dẫn module cũ
terraform state list | grep 'module.storage'
# Di chuyển từng resource lên cấp root
terraform state mv module.storage.aws_s3_bucket.my_bucket aws_s3_bucket.my_bucket
terraform state mv module.storage.aws_dynamodb_table.locks aws_dynamodb_table.locks
# ... lặp lại cho mỗi resource
Sau khi di chuyển xong, cập nhật các file .tf của bạn để khớp với địa chỉ mới. Rồi chạy terraform plan — nếu hiển thị "No changes", state và config đã đồng bộ trở lại.
Backup state trước khi bắt đầu
Trước khi chỉnh sửa bất kỳ provider config nào trong quá trình refactor, hãy tạo snapshot:
cp terraform.tfstate terraform.tfstate.backup-$(date +%Y%m%d)
Dùng remote state? Kéo một bản local trước:
terraform state pull > state-backup.json
File state là JSON thuần túy. Nếu bạn muốn grep qua các tham chiếu provider hoặc khám phá cấu trúc mà không cần cài thêm công cụ, công cụ YAML ↔ JSON Converter tại ToolCraft rất tiện — dán JSON vào và duyệt ngay trên trình duyệt. Dữ liệu không bị upload lên đâu cả, điều này quan trọng khi file state của bạn chứa thông tin IAM credentials hoặc resource ARN.
Kiểm tra lại
Sau khi áp dụng bất kỳ cách sửa nào ở trên, hãy chạy qua checklist này:
# Khởi tạo lại các provider
terraform init
# Xác nhận không có thay đổi ngoài ý muốn
terraform plan
# Kiểm tra nhanh một resource cụ thể vẫn đang được ánh xạ tới hạ tầng thực
terraform state show <resource_address>
"No changes" trong kết quả plan có nghĩa là state và provider config đã được căn chỉnh đúng — không có hạ tầng nào bị thay đổi trong quá trình này.
Bài học rút ra
- Migrate state trước khi xóa provider block. Luôn cập nhật state trước. Xóa config sau. Làm ngược lại chính xác là cách bạn rơi vào lỗi này.
terraform state replace-providerlà lệnh ít người biết đến. Nó được tạo ra chính xác cho việc refactor provider và gọn gàng hơn nhiều so với các phương án thay thế — nhưng hầu như không ai biết nó tồn tại cho đến khi gặp đúng tình huống này.- Provider có phạm vi module tạo ra sự ràng buộc chặt chẽ. Các resource trong module có block
providerriêng sẽ bị khóa vào đường dẫn đó trong state. Thay vào đó hãy truyền provider tường minh qua tham sốproviders— các lần refactor về sau sẽ ít đau đầu hơn nhiều. - State, không phải file
.tf, mới là nguồn sự thật tại thời điểm plan. Terraform khớp địa chỉ trong state với địa chỉ trong config. Nếu chúng lệch nhau, không có gì chạy được. Sửa state trước.