Cách khắc phục lỗi 'Invalid legacy provider address' trong Terraform 0.13+

Tóm tắt: Cách khắc phục trong 30 giây

Lỗi này xảy ra vì từ phiên bản Terraform 0.13 trở đi, hệ thống yêu cầu một namespace đầy đủ (như hashicorp/aws) thay vì chỉ một tên ngắn gọn (aws). Nếu mã nguồn của bạn trông có vẻ đúng nhưng lỗi vẫn tiếp diễn, có thể state file của bạn vẫn đang sử dụng định dạng cũ. Hãy chạy lệnh sau để khắc phục:

terraform state replace-provider "registry.terraform.io/-/aws" "hashicorp/aws"

Sau khi hoàn tất, hãy chạy terraform init để đồng bộ hóa mọi thứ.

Tại sao lỗi này xảy ra

Trước phiên bản 0.13, Terraform hoạt động như một hệ sinh thái khép kín. Nó mặc định rằng mọi provider đều đến trực tiếp từ HashiCorp. Bạn chỉ cần viết provider "aws" là mã sẽ hoạt động. Tuy nhiên, khi hệ sinh thái phát triển với hàng nghìn cộng đồng provider, Terraform đã chuyển sang cấu trúc namespace phân cấp trên Registry chính thức.

Thông báo Invalid legacy provider address là cách Terraform cho biết nó đã tìm thấy một provider tên là aws nhưng không biết ai là chủ sở hữu của nó. Nó sử dụng registry.terraform.io/-/aws như một trình giữ chỗ tạm thời. Bạn phải thông báo cho Terraform rằng provider "legacy" (cũ) này thực chất là phiên bản chính thức của hashicorp/aws.

Ba cách để khắc phục quá trình di chuyển

1. Xác định rõ ràng các Provider trong mã nguồn

Các tệp .tf của bạn cần chỉ định chính xác cho Terraform nơi để tải các provider. Hãy mở tệp versions.tf hoặc main.tf và thêm một khối required_providers. Điều này đặc biệt quan trọng nếu bạn đang sử dụng các phiên bản cụ thể như 3.x hoặc 4.x.

terraform {
  required_version = ">= 0.13"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0" 
    }
  }
}

2. Bản đồ lại Provider trong State File

Ngay cả khi bạn đã sửa mã nguồn, tệp terraform.tfstate của bạn có thể vẫn còn bám theo các tên cũ. Đối với các dự án có hàng trăm tài nguyên, bạn chắc chắn không muốn chỉnh sửa tệp JSON theo cách thủ công. Thay vào đó, hãy sử dụng công cụ CLI tích hợp sẵn để hoán đổi các địa chỉ.

Chạy các lệnh sau dựa trên các provider mà bạn sử dụng:

# Cho AWS
terraform state replace-provider "registry.terraform.io/-/aws" "hashicorp/aws"

# Cho Azure
terraform state replace-provider "registry.terraform.io/-/azurerm" "hashicorp/azurerm"

# Cho Google Cloud
terraform state replace-provider "registry.terraform.io/-/google" "hashicorp/google"

Terraform sẽ liệt kê các thay đổi và yêu cầu nhập yes để xác nhận. Việc này sẽ cập nhật "danh bạ địa chỉ" nội bộ cho hạ tầng của bạn.

3. Sử dụng công cụ nâng cấp tự động

Nếu bạn vẫn đang sử dụng binary phiên bản v0.13, bạn có thể để Terraform thực hiện các công việc nặng nhọc. Hãy chạy lệnh này trong thư mục gốc của bạn:

terraform 0.13upgrade

Công cụ này sẽ quét cấu hình của bạn và tự động tạo các khối required_providers cần thiết. Đây là một cách tiết kiệm thời gian tuyệt vời cho các môi trường phức tạp với nhiều module.

Truy tìm các tham chiếu Legacy ẩn giấu

Đôi khi lỗi vẫn còn tồn tại vì một module bên thứ ba hoặc một data source terraform_remote_state vẫn đang sử dụng quy ước đặt tên cũ. Nếu các cách khắc phục thông thường thất bại, bạn cần kiểm tra xem điều gì đang xảy ra bên trong state file.

Tải state của bạn về một tệp cục bộ để kiểm tra:

terraform state pull > my_infrastructure.json

Các tệp state có thể rất lớn—đôi khi lên đến hơn 5.000 dòng JSON dày đặc. Để hiểu rõ nội dung, tôi thường sử dụng một Trình chuyển đổi YAML ↔ JSON. Việc chuyển đổi JSON lộn xộn đó sang YAML giúp việc tìm kiếm provider: provider.aws dễ dàng hơn nhiều. Nếu bạn tìm thấy một cái, điều đó có nghĩa là một tài nguyên vẫn đang bị liên kết với địa chỉ cũ (legacy). Mẹo nhỏ: Hãy sử dụng các công cụ chạy cục bộ hoặc chỉ trên trình duyệt như ToolCraft để giữ dữ liệu state nhạy cảm của bạn không bị gửi lên các máy chủ bên thứ ba.

Cách xác minh việc khắc phục

Đừng vội cho rằng lỗi đã được khắc phục chỉ vì lệnh đã chạy xong. Hãy thực hiện ba bước kiểm tra sau:

• Khởi tạo: Chạy terraform init. Nó sẽ tải provider từ đường dẫn đầy đủ hashicorp/aws.
• Kiểm tra: Chạy terraform providers. Hãy tìm bất kỳ mục nào có chứa dấu gạch ngang (-). Bạn cần thấy các đường dẫn sạch sẽ dạng registry.terraform.io/hashicorp/....
• Lập kế hoạch: Chạy terraform plan. Nếu lỗi không còn và bạn thấy thông báo "No changes. Your infrastructure matches the configuration," nghĩa là bạn đã di chuyển thành công.

Tham khảo lệnh nhanh

  Mục tiêu
  Lệnh




  Tự động sửa cấu hình
  `terraform 0.13upgrade`


  Cập nhật state thủ công
  `terraform state replace-provider [OLD] [NEW]`


  Kiểm tra tất cả các provider
  `terraform providers`