Cách sửa lỗi Terraform "Error: Unsupported argument" do tên thuộc tính hoặc phiên bản provider

Thông Báo Lỗi

Khi chạy terraform plan hoặc terraform validate, bạn thấy thông báo kiểu như này:

Error: Unsupported argument

  on main.tf line 42, in resource "aws_instance" "web":
  42:   instance_type_size = "t3.micro"

An argument named "instance_type_size" is not expected here.

Terraform đang chỉ thẳng vào một dòng cụ thể và nói rằng nó không nhận ra thuộc tính đó. Điều này thực ra rất hữu ích — lỗi cho bạn biết chính xác chỗ cần xem. Nguyên nhân hầu như luôn là một trong ba thứ: lỗi đánh máy, sai chữ hoa/thường, hoặc phiên bản code của bạn không khớp với plugin provider.

Tại Sao Lỗi Này Xảy Ra

Mỗi provider của Terraform đi kèm với một schema — danh sách nghiêm ngặt các argument hợp lệ cho từng loại resource. Nếu bạn truyền vào thứ gì đó nằm ngoài danh sách đó, trình phân tích cú pháp sẽ dừng ngay. Các nguyên nhân phổ biến nhất:

Lỗi đánh máy: Viết ami_id trong khi argument đúng chỉ là ami. Thêm một chữ thừa là lỗi ngay.
Sai chữ hoa/thường: Terraform dùng snake_case ở khắp nơi. Nếu quen với CloudFormation hay ARM templates, bạn dễ viết InstanceType thay vì instance_type.
Provider bị lệch phiên bản: AWS provider v5.0 đã thêm ipv6_ipam_pool_id vào aws_vpc. Nếu project của bạn đang ghim ở v4.x, argument đó đơn giản là không tồn tại trong schema của phiên bản bạn đang dùng.
Thuộc tính đã bị khai tử: Các argument bị xóa trong các bản cập nhật lớn. Ví dụ, block lifecycle_rule trong S3 provider đã bị tái cấu trúc giữa v3 và v4.

Cách Sửa Từng Bước

1. Kiểm Tra Lỗi Đánh Máy và Chữ Hoa/Thường

Bắt đầu từ điều đơn giản nhất. Đọc kỹ tên thuộc tính từng ký tự một. Terraform dùng snake_case xuyên suốt — không có ngoại lệ cho các argument của resource có sẵn.

# SAI — CamelCase do quen tay với CloudFormation
resource "aws_instance" "example" {
  Ami = "ami-12345678"
}

# ĐÚNG
resource "aws_instance" "example" {
  ami = "ami-12345678"
}

Cũng chú ý đến việc nhầm số ít/số nhiều: security_group_id và security_group_ids. Terraform coi đó là hai argument hoàn toàn khác nhau.

2. Kiểm Tra Phiên Bản Provider Đang Thực Sự Chạy

Code của bạn có thể hoàn toàn đúng — chỉ là không đúng với phiên bản đang cài locally. Chạy lệnh:

terraform version

Bạn sẽ thấy output kiểu như này:

Terraform v1.7.4
on linux_amd64
+ provider registry.terraform.io/hashicorp/aws v4.67.0

Sau đó xem ràng buộc phiên bản trong versions.tf hoặc main.tf:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0" # Ghim ở 4.x — không dùng được tính năng của 5.x
    }
  }
}

Nếu argument bạn đang dùng được giới thiệu từ v5.0 mà bạn đang ghim ở v4.x, đó chính là vấn đề.

3. Đọc Tài Liệu Đúng Phiên Bản Của Bạn, Không Phải Phiên Bản Mới Nhất

Terraform Registry mặc định hiển thị tài liệu của provider mới nhất. Đừng tin vào đó một cách mù quáng. Dùng dropdown chọn phiên bản để khớp với file .terraform.lock.hcl của bạn, sau đó tìm resource và xác nhận argument đó tồn tại ở phiên bản đó.

File lock cho bạn biết chính xác những gì đã được cài:

provider "registry.terraform.io/hashicorp/aws" {
  version     = "4.67.0"
  constraints = "~> 4.0"
}

4. Cập Nhật Provider Nếu Cần

Cần tính năng từ v5.x? Cập nhật ràng buộc phiên bản, sau đó chạy:

terraform init -upgrade

Lệnh này tải về phiên bản mới nhất trong ràng buộc bạn đã cập nhật và tạo lại file lock. Hãy thử trong workspace không phải production trước — các bản nâng cấp major thường có breaking changes ảnh hưởng đến các resource khác.

5. Chú Ý Sự Khác Biệt Giữa Block và Attribute

Đôi khi thứ trông như attribute thực ra là một nested block. Nội dung thông báo lỗi sẽ cho bạn biết:

Attribute viết theo dạng block: Bạn thiếu dấu = — ví dụ phải là tags = {} chứ không phải tags {}.
Block viết theo dạng attribute: Bạn thêm dấu = không cần thiết — ví dụ phải là ingress {} chứ không phải ingress = {}.

Kiểm Tra Lại

Sau khi sửa xong, chạy lần lượt ba lệnh sau:

Định dạng: terraform fmt — chuẩn hóa khoảng trắng và bắt các lỗi cú pháp rõ ràng.
Kiểm tra: terraform validate — kiểm tra local, không cần gọi API. Kết quả Success! The configuration is valid. nghĩa là các lỗi schema đã được giải quyết.
Lên kế hoạch: terraform plan — provider lúc này xử lý config của bạn với trạng thái cloud thực tế, phát hiện các vấn đề runtime mà validate không thấy được.

Mẹo Phòng Tránh

Extension HashiCorp cho VS Code: Thêm IntelliSense nhận biết schema vào editor. Các argument không được hỗ trợ sẽ bị gạch chân ngay trong thời gian thực trước khi bạn chạy plan, dựa trên các provider trong thư mục .terraform của bạn.
Ghim phiên bản: Block required_providers với ~> 5.0 ngăn việc bị ảnh hưởng bất ngờ khi provider ra v6.0 và đổi tên hoặc xóa các argument.
Đọc changelog trước khi nâng cấp: Các repo GitHub của provider đều có file CHANGELOG.md. Phần "Breaking Changes" thường rất ngắn — năm phút đọc ở đó có thể tiết kiệm hàng giờ debug.