Dòng chữ đỏ "chết chóc"
Bạn vừa mới clone một repository mới, cấu hình các biến môi trường và chạy terraform init. Thay vì khởi tạo thành công, bạn lại nhận được một thông báo thẳng thừng: Error: Unsupported Terraform Core version. Về cơ bản, nó có nghĩa là bản Terraform binary cục bộ của bạn không được "mời" tham gia vào hạ tầng cụ thể này.
Đây là một vấn đề gây đau đầu phổ biến trong môi trường làm việc nhóm hoặc khi khôi phục một dự án cũ. Mặc dù nó có vẻ như là một trở ngại, nhưng thực chất đây là một tính năng bảo mật quan trọng được thiết kế để giữ cho trạng thái hạ tầng (state) luôn nhất quán trên các máy khác nhau.
Nguyên nhân gốc rễ: Ràng buộc phiên bản
Terraform dựa vào thiết lập required_version bên trong khối cấu hình terraform {}. Điều này xác định rõ ràng phiên bản CLI nào được phép tác động vào mã nguồn. Nó ngăn chặn tình trạng "nhảy phiên bản file state", nơi các phiên bản khác nhau ghi vào file state và có khả năng làm hỏng siêu dữ liệu (metadata) hoặc khóa hoàn toàn các phiên bản cũ hơn.
Hãy kiểm tra file versions.tf hoặc main.tf của bạn. Bạn có thể sẽ tìm thấy một ràng buộc như thế này:
terraform {
required_version = ">= 1.6.0"
}
Nếu máy cục bộ của bạn đang chạy phiên bản 1.3.0, Terraform sẽ dừng bạn ngay lập tức vì 1.3.0 không đáp ứng yêu cầu "1.6.0 trở lên".
Cách 1: Cập nhật cấu hình
Nếu bạn đang làm việc một mình hoặc là người dẫn dắt dự án và quyết định đã đến lúc chuyển sang phiên bản mới hơn, bạn có thể sửa đổi ràng buộc. Hãy tìm khối terraform và điều chỉnh chuỗi required_version cho phù hợp với môi trường cục bộ của bạn.
Bạn có một vài cách để định nghĩa điều này:
# Tùy chọn A: Ghim chặt phiên bản (Bắt buộc mọi người dùng chung một phiên bản)
terraform {
required_version = "1.3.0"
}
# Tùy chọn B: Toán tử Pessimistic (Cho phép 1.3.1, 1.3.2, nhưng không cho phép 1.4.0)
terraform {
required_version = "~> 1.3.0"
}
# Tùy chọn C: Phiên bản tối thiểu (Cách tiếp cận linh hoạt nhất)
terraform {
required_version = ">= 1.3.0"
}
Sau khi lưu file, hãy chạy lại terraform init để xác nhận kết quả.
Cách 2: Cách tiếp cận chuyên nghiệp (Trình quản lý phiên bản)
Trong môi trường DevOps chuyên nghiệp, bạn không nên bẻ lái mã nguồn để phù hợp với máy cục bộ của mình. Thay vào đó, máy của bạn nên thích nghi với nhu cầu của dự án. Nếu một dự án yêu cầu phiên bản 1.6.0, bạn cần phải cài đặt 1.6.0.
Các công cụ như tfenv (macOS/Linux) hoặc tfutils/tfenv-windows là những "vị cứu tinh" ở đây. Chúng cho phép bạn luân chuyển giữa nhiều phiên bản mà không cần phải thay đổi các file binary một cách thủ công.
Chuyển đổi phiên bản với tfenv:
- Cài đặt phiên bản cần thiết:
tfenv install 1.6.0 - Kích hoạt nó:
tfenv use 1.6.0 - Xác nhận thay đổi:
terraform version
Đối với người dùng asdf, quy trình cũng nhanh chóng không kém:
asdf install terraform 1.6.0
asdf local terraform 1.6.0
Thủ phạm lén lút: File State
Đôi khi các ràng buộc mã nguồn của bạn trông có vẻ hoàn hảo, nhưng bạn vẫn gặp lỗi. Điều này thường xảy ra vì File State đã bị sửa đổi bởi một phiên bản mới hơn. Terraform nhúng phiên bản được sử dụng lần cuối trực tiếp vào siêu dữ liệu của state. Nếu một đồng đội đã áp dụng thay đổi bằng phiên bản 1.7.0 và bạn cố gắng chạy plan với phiên bản 1.3.0, Terraform sẽ chặn bạn để ngăn chặn việc hỏng dữ liệu.
Khi điều này xảy ra, bạn thường bắt buộc phải nâng cấp Terraform CLI cục bộ để khớp hoặc vượt quá phiên bản được ghi trong file state.
Xác minh và kiểm tra
Xác nhận việc khắc phục bằng cách kiểm tra phiên bản đang hoạt động trước:
terraform version
Sau đó, chạy thử để đảm bảo các ràng buộc đã được thỏa mãn:
terraform plan
Nếu bạn thấy một bản tóm tắt như "Plan: 5 to add, 0 to change, 0 to destroy," bạn đã vượt qua rào cản thành công.
Các phương pháp hay nhất để phòng ngừa
Để ngăn lỗi này tái diễn, hãy thêm file .terraform-version vào thư mục gốc của repo. Hầu hết các trình quản lý phiên bản sẽ phát hiện file này và tự động chuyển đổi môi trường của bạn ngay khi bạn cd vào thư mục.
Khi làm việc với các cấu hình phức tạp, việc giữ cho dữ liệu sạch sẽ là vô cùng quan trọng. Tôi thường sử dụng Bộ chuyển đổi YAML ↔ JSON để kiểm tra kỹ các file biến hoặc siêu dữ liệu bên ngoài. Đây là một cách đơn giản để đảm bảo cấu trúc dữ liệu của bạn hợp lệ trước khi Terraform chạm vào chúng.
Cuối cùng, tránh sử dụng tag latest trong các pipeline CI/CD. Hãy ghim rõ ràng phiên bản runner của bạn (ví dụ: trong GitHub Actions) để khớp với required_version. Điều này giúp ngăn chặn các bản build của bạn bị lỗi ngay khi Terraform ra mắt một phiên bản lớn mới.