Cách sửa lỗi Terraform 'Failed to query available provider packages' – Lỗi kết nối registry.terraform.io

Thông báo lỗi

Việc chạy terraform init thường là một quá trình suôn sẻ. Tuy nhiên, mọi thứ sẽ đình trệ nếu Terraform không thể kết nối với HashiCorp Registry để tải các provider như AWS hoặc Azure. Khi máy tính của bạn thiếu đường truyền internet rõ ràng hoặc không thể phân giải tên miền, bạn sẽ gặp phải trở ngại này:

Error: Failed to query available provider packages

Could not retrieve the list of available versions for provider hashicorp/aws: 
could not connect to registry.terraform.io: dial tcp: lookup 
registry.terraform.io: no such host

Xác định nguyên nhân gốc rễ

Terraform thực chất đang "gào thét vào khoảng không" mà không nhận được phản hồi. Vì lỗi này xảy ra ở lớp mạng, Terraform thậm chí không thể tìm thấy địa chỉ IP cho registry.terraform.io. Điều này thường do ba nguyên nhân chính sau:

Lỗi DNS: Trình phân giải DNS của hệ thống không thể chuyển đổi tên miền.
Proxy doanh nghiệp: Tường lửa đang chặn lưu lượng truy cập, yêu cầu các biến môi trường cụ thể để cho phép lưu lượng HTTPS đi qua cổng 443.
Cách ly hoàn toàn: Bạn đang làm việc trong môi trường air-gapped không có đường dẫn vật lý tới mạng công cộng.

Giải pháp 1: Kiểm tra DNS và mạng thủ công

Bước đầu tiên là xác định xem vấn đề xảy ra trên toàn hệ thống hay chỉ riêng với Terraform. Sử dụng nslookup hoặc dig để kiểm tra trực tiếp hostname.

nslookup registry.terraform.io

Phản hồi "NXDOMAIN" hoặc "non-existent domain" xác nhận rằng cấu hình DNS của bạn đang bị lỗi. Trên Linux, hãy kiểm tra tệp /etc/resolv.conf. Đảm bảo bạn đã liệt kê các nameserver đáng tin cậy, chẳng hạn như 8.8.8.8 của Google hoặc IP DNS nội bộ của công ty bạn.

Nếu DNS có vẻ ổn nhưng terraform init vẫn bị treo, hãy thử thực hiện "bắt tay" thủ công với registry qua curl:

curl -I https://registry.terraform.io

Giải pháp 2: Cấu hình HTTP Proxy

Các thiết lập trong doanh nghiệp thường chặn lưu lượng truy cập trực tiếp ra ngoài qua cổng 443 vì lý do bảo mật. Trong những trường hợp này, bạn phải chỉ định rõ ràng cho Terraform máy chủ proxy của công ty. Hãy thiết lập các biến môi trường này trong terminal của bạn trước khi chạy bất kỳ lệnh Terraform nào.

Cho Linux và macOS:

export HTTP_PROXY="http://proxy.yourcompany.com:8080"
export HTTPS_PROXY="http://proxy.yourcompany.com:8080"
export NO_PROXY="localhost,127.0.0.1,169.254.169.254"

Cho Windows (PowerShell):

$env:HTTP_PROXY="http://proxy.yourcompany.com:8080"
$env:HTTPS_PROXY="http://proxy.yourcompany.com:8080"

Nếu proxy của bạn yêu cầu đăng nhập, hãy sử dụng định dạng http://user:password@proxy.url:port. Sau khi thiết lập xong, Terraform sẽ định tuyến các yêu cầu provider thông qua đường truyền đã chỉ định.

Giải pháp 3: Thiết lập Local Filesystem Mirror

Môi trường ngoại tuyến yêu cầu một cách tiếp cận khác vì chúng không thể kết nối tới registry. Bạn sẽ cần tải xuống các tệp binary của provider trên một máy tính có kết nối mạng và chuyển chúng — thường qua USB bảo mật hoặc jump box nội bộ — sang máy chủ ngoại tuyến của mình.

Sau khi di chuyển các tệp, hãy tạo một tệp cấu hình CLI (.terraformrc trên Linux/macOS hoặc terraform.rc trên Windows) để chỉ dẫn Terraform tìm kiếm tại địa phương trước.

Đặt khối mã sau vào ~/.terraformrc:

provider_installation {
  filesystem_mirror {
    path    = "/usr/share/terraform/providers"
    include = ["hashicorp/*", "registry.terraform.io/*/*"]
  }
  direct {
    exclude = ["hashicorp/*", "registry.terraform.io/*/*"]
  }
}

Đảm bảo cấu trúc thư mục của bạn khớp chính xác với những gì Terraform mong đợi. Nó sẽ trông như thế này:

/usr/share/terraform/providers/registry.terraform.io/hashicorp/aws/5.0.0/linux_amd64/terraform-provider-aws_v5.0.0_x5

Kiểm tra kết quả

Để xác nhận việc sửa lỗi, hãy thực hiện ba bước sau:

Xóa sạch cache cục bộ bằng cách xóa thư mục .terraform/ và tệp .terraform.lock.hcl.
Chạy lại lệnh terraform init.
Kiểm tra dấu tích xanh: ✔ HashiCorp AWS provider v5.x.x successfully installed.

Nếu bước "Finding latest version..." hoàn tất nhanh chóng mà không bị hết thời gian chờ, bạn đã có thể tiếp tục công việc.

Phòng ngừa và Các thực hành tốt nhất

Để giữ cho việc triển khai của bạn ổn định, hãy cân nhắc các thói quen sau:

Bật Global Caching: Tiết kiệm băng thông và thời gian bằng cách lưu cache các provider cục bộ. Thêm plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" vào cấu hình của bạn.
Khóa các phiên bản: Luôn commit tệp .terraform.lock.hcl lên Git. Điều này ngăn ngừa các lỗi "chạy được trên máy tôi" khi đồng nghiệp có tốc độ kết nối hoặc bộ nhớ đệm DNS khác nhau.
Kiểm tra các tuyến mạng: Nếu bạn đang xây dựng trong một VPC bị hạn chế, hãy xác nhận rằng NAT Gateway hoặc Internet Gateway của bạn thực sự có thể kết nối được.

Khi tôi đang thiết lập ranh giới mạng hoặc gỡ lỗi các quy tắc tường lửa phức tạp, tôi thường sử dụng IP Subnet Calculator. Đó là một cách đơn giản để kiểm tra các dải CIDR và đảm bảo các gateway của tôi nằm đúng vị trí trước khi lãng phí hàng giờ để đuổi theo một "bóng ma" DNS.