Cách khắc phục nhanh
Bạn có hai cách để giải quyết vấn đề này. Cách dễ nhất là nâng cấp Terraform CLI cục bộ để khớp với phiên bản được liệt kê trong lỗi. Nếu bạn không thể nâng cấp—có lẽ do các hạn chế của CI/CD—bạn sẽ cần phải điều chỉnh metadata của state theo cách thủ công. Dưới đây là quy trình sửa lỗi 'ngoại khoa' gồm ba bước:
- Tải state về (Pull):
terraform state pull > temp_state.json - Chỉnh sửa phiên bản: Mở tệp và thay đổi
"terraform_version": "1.6.0"thành phiên bản bạn yêu cầu (ví dụ:"1.4.0"). - Đẩy state lên lại (Push):
terraform state push temp_state.json
Tại sao lỗi này xảy ra
Terraform bảo vệ các file state của mình rất nghiêm ngặt. Mỗi khi bạn chạy terraform apply, CLI sẽ đóng dấu phiên bản hiện tại vào file state. Nếu một đồng nghiệp sử dụng v1.6.0 trong khi những người còn lại dùng v1.4.0, chỉ một lần 'apply' đó sẽ khóa quyền truy cập của tất cả những người khác.
Các bản build cũ hơn sẽ từ chối đọc các file state được tạo bởi các phiên bản mới hơn. Việc kiểm tra an toàn này giúp ngăn chặn khả năng hỏng dữ liệu, vì các phiên bản mới có thể giới thiệu các resource schema mà CLI cũ không hiểu được. Điều này thường xảy ra khi một nhà phát triển cài đặt phiên bản mới qua Homebrew hoặc Chocolatey mà không nhận ra nó đã nhảy vọt so với môi trường production.
Các bước phục hồi chi tiết
Cách 1: Hạ cấp Metadata của State thủ công
Sử dụng phương pháp này nếu bạn bắt buộc phải ở lại phiên bản Terraform cũ hơn. Chúng ta sẽ đánh lừa Terraform rằng state này được tạo bởi một bản build cũ hơn.
1. Tải state hiện tại xuống Chạy lệnh này để tạo một bản sao cục bộ của remote state. Cách này hoạt động với S3, GCS, và Azure Blob storage.
terraform state pull > repair_state.json
2. Chỉnh sửa tệp JSON
Mở repair_state.json trong VS Code hoặc Vim. Bạn sẽ thấy thông tin phiên bản ngay trên cùng:
{
"version": 4,
"terraform_version": "1.6.0",
"serial": 125,
...
}
Thay đổi giá trị terraform_version sao cho khớp với môi trường của bạn (ví dụ: 1.4.0). Giữ nguyên các trường version: 4 và serial. Lưu các thay đổi.
3. Tải state đã sửa lên Đẩy tệp đã chỉnh sửa trở lại remote backend của bạn. Terraform sẽ coi đây là một bản cập nhật thủ công và tăng số serial.
terraform state push repair_state.json
Mẹo nhỏ: Nếu bạn thấy lỗi 'lineage', điều đó có nghĩa là cấu trúc tệp đã vô tình bị thay đổi. Hãy đảm bảo bạn chỉ thay đổi chuỗi phiên bản.
Cách 2: Đồng bộ phiên bản bằng tfenv
Thay vì can thiệp vào file state, tốt hơn hết là bạn nên sử dụng đúng phiên bản mà đồng nghiệp đang dùng. Các trình quản lý phiên bản giúp việc này trở nên dễ dàng. Nếu state yêu cầu v1.6.0, chỉ cần chuyển sang phiên bản đó:
# Cài đặt và chuyển đổi trong vài giây
tfenv install 1.6.0
tfenv use 1.6.0
# Kiểm tra thay đổi
terraform version
Xác nhận khắc phục
Sau khi bạn đã đẩy state lên hoặc cập nhật CLI, hãy chạy lệnh plan để xác minh mọi thứ đã đồng bộ trở lại:
terraform plan
Lỗi sẽ biến mất. Nếu bạn đã hạ cấp file state, lệnh plan sẽ báo "No changes," xác nhận rằng code cục bộ và remote state cuối cùng đã sử dụng chung một ngôn ngữ.
Cách ngăn chặn sự sai lệch phiên bản
Cách tốt nhất để tránh các trường hợp khẩn cấp lúc nửa đêm là khóa phiên bản trong code của bạn. Bằng cách thêm ràng buộc required_version, CLI sẽ chặn bất kỳ nhà phát triển nào sử dụng sai phiên bản trước khi họ có thể chạm vào file state.
terraform {
# Cố định vào một phiên bản minor cụ thể
required_version = "~> 1.4.0"
backend "s3" {
bucket = "my-terraform-state"
key = "prod/network.tfstate"
}
}
Với khối lệnh này, ai đó cố gắng chạy v1.6.0 sẽ nhận được thông báo lỗi ngay lập tức. Việc kiểm tra đơn giản này giúp nhóm của bạn luôn đồng bộ và các file state được an toàn khỏi các nâng cấp vô ý.