Sửa lỗi 'Value for undeclared variable' trong Terraform

Tình huống

Hãy tưởng tượng lúc đó là 2 giờ sáng. Bạn đang đẩy một bản sửa lỗi gấp (hotfix) để thay đổi quy mô cơ sở dữ liệu production từ t3.medium lên m5.large. Bạn cập nhật tệp terraform.tfvars với kích thước instance mới, nhấn lưu và chạy terraform plan. Thay vì một đợt triển khai suôn sẻ, terminal lại hiện ra một loạt chữ đỏ:

Error: Value for undeclared variable

The root module does not declare a variable named "instance_size" but a value was
assigned to it in terraform.tfvars. To declare variable "instance_size", place this
block in one of your .tf files:

variable "instance_size" {
  type = string
}

Terraform là ngôn ngữ có kiểu dữ liệu nghiêm ngặt (strictly typed) và yêu cầu khai báo rõ ràng. Không giống như các ngôn ngữ động nơi bạn có thể truyền các cặp key-value tùy ý, Terraform yêu cầu một khối variable tương ứng cho mọi giá trị trong tệp .tfvars hoặc cờ -var của bạn. Nếu bản thiết kế (blueprint) không mong đợi dữ liệu đó, Terraform sẽ từ chối xử lý.

Tại sao Terraform lại báo lỗi

Trong giai đoạn khởi tạo, Terraform tự động tải mọi tệp .tfvars trong thư mục hiện tại của bạn. Khi gặp một key như max_db_connections = 100, nó sẽ ngay lập tức quét các tệp .tf để tìm khối variable "max_db_connections" {} tương ứng. Nếu thiếu định nghĩa đó, quá trình sẽ dừng lại để ngăn các dữ liệu cấu hình bị gõ sai hoặc bị thừa làm ảnh hưởng đến trạng thái (state) của bạn.

Các nguyên nhân phổ biến gây ra lỗi này bao gồm:

• Khối biến bị quên: Bạn đã định nghĩa giá trị trong terraform.tfvars nhưng bỏ qua việc khai báo variable trong variables.tf.
• Lỗi đánh máy: Một sai sót đơn giản, chẳng hạn như viết instane_type trong tệp này và instance_type trong tệp khác.
• Phân biệt chữ hoa chữ thường: Terraform coi Database_Name và database_name là hai thực thể hoàn toàn khác nhau.
• Module gốc so với Module con: Bạn có thể đang cố gắng thiết lập một biến cho module con trực tiếp từ tệp .tfvars gốc, điều mà Terraform không cho phép.

Cách khắc phục nhanh

Để việc triển khai trở lại đúng hướng, hãy xác định tên biến từ thông báo lỗi. Sau đó, thêm một khối khai báo vào tệp variables.tf hoặc bất kỳ tệp .tf nào khác trong thư mục gốc của bạn.

# variables.tf

variable "instance_size" {
  description = "Loại instance EC2, ví dụ: m5.large"
  type        = string
}

Sau khi bạn lưu khối này, Terraform sẽ nhận ra giá trị được gán trong tệp biến của bạn và tiếp tục thực hiện plan.

Các phương pháp hay nhất để cấu hình sạch hơn

Đừng để việc không khớp biến làm chậm quy trình CI/CD của bạn. Hãy sử dụng các chiến lược sau để giữ cho mã nguồn luôn đồng bộ.

1. Duy trì ánh xạ 1:1

Mỗi mục nhập trong tệp .tfvars của bạn nên có một bản sao tương ứng trong variables.tf. Nếu bạn loại bỏ một cài đặt—ví dụ: chuyển từ 10 xuống 20 subnet—hãy nhớ xóa biến không sử dụng khỏi cả hai tệp. Mã thừa (dead code) sẽ dẫn đến sự nhầm lẫn trong quá trình kiểm tra (audit).

2. Truyền biến vào Module đúng cách

Bạn không thể chèn trực tiếp các giá trị vào một module con từ terraform.tfvars gốc. Thay vào đó, bạn phải khai báo biến ở module gốc, sau đó truyền nó một cách rõ ràng vào khối module.

# root/variables.tf
variable "app_port" { type = number }

# root/main.tf
module "web_server" {
  source = "./modules/web"
  port   = var.app_port 
}

3. Kiểm tra (Validate) sớm và thường xuyên

Chạy terraform validate như một phần của quy trình làm việc tại máy cục bộ hoặc pre-commit hook. Lệnh này rất nhanh. Nó phát hiện các biến chưa được khai báo trong vài giây mà không cần kiểm tra nhà cung cấp đám mây hoặc làm mới tệp trạng thái (state file).

4. Kiểm tra các biến môi trường

Đôi khi thủ phạm không phải là một tệp tin. Terraform cũng tìm kiếm các biến shell có tiền tố TF_VAR_. Nếu bạn đã thiết lập export TF_VAR_api_key="12345" trong terminal hoặc Jenkins agent, Terraform sẽ mong đợi tìm thấy một khối variable "api_key" {} trong mã của bạn.

Xác minh

Xác nhận việc sửa lỗi bằng cách chạy một lệnh plan mục tiêu. Nếu khai báo chính xác, văn bản lỗi màu đỏ sẽ được thay thế bằng một kế hoạch thực thi tiêu chuẩn.

terraform plan -out=tfplan

Việc sửa lỗi thành công sẽ dẫn đến thông báo "No changes" hoặc danh sách các cập nhật hạ tầng dự kiến. Nếu lỗi biến mất, các phần gán và khai báo của bạn cuối cùng đã đồng bộ.

Tóm tắt cho người xử lý sự cố lúc 2 giờ sáng

• Lấy tên biến từ thông báo lỗi.
• Tìm kiếm trong các tệp .tf của bạn chuỗi variable "tên_biến_tại_đây".
• Nếu thiếu, hãy thêm khối đó vào variables.tf.
• Kiểm tra lỗi đánh máy hoặc sự khác biệt giữa CHỮ HOA và chữ thường.
• Chạy terraform validate để xác nhận việc sửa lỗi.