Sửa lỗi Terraform 'Permission Denied (publickey)' khi tải Module

Vấn đềBạn chạy terraform init trên một máy mới hoặc một CI/CD runner, kỳ vọng một khởi đầu suôn sẻ. Thay vào đó, quá trình bị dừng lại đột ngột. Trong khi tệp main.tf của bạn trông có vẻ hoàn hảo, Terraform lại thất bại trong việc lấy module từ kho lưu trữ Git riêng tư của bạn. Bạn thấy thông báo lỗi exit status 128 đáng sợ theo sau là thông báo Permission denied (publickey).

Error: Failed to download module

Could not download module "network" source code from "git@github.com:org/terraform-modules.git": 
error downloading 'ssh://git@github.com/org/terraform-modules.git': 
exit status 128: Cloning into '.terraform/modules/network'...
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Điều này thường xảy ra do quá trình SSH handshake giữa Git client cục bộ và nhà cung cấp (GitHub, GitLab hoặc Bitbucket) bị lỗi. Ngay cả khi các key của bạn hoạt động với các lệnh git clone tiêu chuẩn, môi trường của Terraform có thể không nhìn thấy chúng.

Nguyên nhân gốc rễTerraform thực tế không xử lý logic SSH. Nó chỉ đơn giản là chuyển giao nhiệm vụ tải xuống cho tệp thực thi git được cài đặt trên hệ thống của bạn. Nếu môi trường Git cục bộ của bạn không thể tìm thấy private key hợp lệ hoặc thiếu thông tin xác thực để giao tiếp với máy chủ từ xa, việc tải xuống sẽ thất bại. Sau đó, Terraform sẽ báo cáo lỗi đó lại cho bạn.

Những nguyên nhân phổ biến nhất bao gồm:

• Một SSH agent không hoạt động hoặc chưa tải private key của bạn.- Quyền truy cập tệp không chính xác trên các tệp ~/.ssh/id_rsa hoặc ~/.ssh/id_ed25519.- SSH public key chưa được đăng ký trong cài đặt của nhà cung cấp Git.- Một lỗi cú pháp nhỏ trong chuỗi source của module.## Các bước khắc phục### 1. Kiểm tra kết nối SSH thủ côngHãy bắt đầu bằng cách loại bỏ Terraform ra khỏi quy trình. Bạn cần xác nhận Git có thể kết nối tới nhà cung cấp. Chạy lệnh sau trong terminal của bạn:

ssh -T git@github.com

Một kết nối thành công sẽ trả về: Hi username! You've successfully authenticated.... Nếu bạn nhận được lỗi quyền truy cập ở đây, thiết lập SSH của bạn chính là nút thắt cổ chai, chứ không phải Terraform.

2. Tải Key vào SSH AgentTrong nhiều trường hợp, key đã tồn tại nhưng không "hoạt động" trong phiên làm việc hiện tại. Điều này thường thấy trong các tab terminal mới hoặc các môi trường tự động. Bạn phải khởi động agent và thêm key của mình một cách thủ công.

# Khởi động agent trong nền
eval "$(ssh-agent -s)"

# Thêm private key của bạn (sử dụng id_ed25519 cho các key hiện đại)
ssh-add ~/.ssh/id_ed25519

3. Sửa quyền truy cập Private KeySSH rất nghiêm ngặt về bảo mật. Nếu private key của bạn có thể được truy cập bởi các người dùng khác trên hệ thống, SSH client sẽ bỏ qua nó hoàn toàn. Thư mục .ssh của bạn cần quyền 700, và private key của bạn yêu cầu quyền 600.

Việc thiết lập các quyền này một cách chính xác là bắt buộc. Nếu bạn không chắc chắn về các giá trị bát phân (octal), Unix Permissions Calculator trên ToolCraft cung cấp một tham chiếu trực quan nhanh chóng. Hãy áp dụng các lệnh sau để bảo mật key của bạn:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519

4. Sử dụng cú pháp Terraform Module rõ ràngĐôi khi Terraform có thể bị nhầm lẫn bởi các URL Git viết tắt. Để an toàn, hãy sử dụng tiền tố git::ssh:// rõ ràng. Điều này cho Terraform biết chính xác giao thức nào cần sử dụng. Ngoài ra, hãy nhớ rằng Terraform sử dụng dấu gạch chéo kép (//) để phân tách đường dẫn kho lưu trữ với một thư mục con bên trong kho lưu trữ đó.

module "vpc" {
  # Định dạng: git::ssh://git@provider/org/repo.git//path/to/module?ref=tag
  source = "git::ssh://git@github.com/acme/infrastructure-modules.git//modules/network?ref=v2.4.0"
}

5. Quản lý nhiều Key với SSH ConfigNếu bạn sử dụng đồng thời các key riêng biệt cho tài khoản GitHub công việc và cá nhân, Git có thể đang cung cấp sai key. Bạn có thể chỉ định key chính xác bằng cách chỉnh sửa tệp ~/.ssh/config:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

Giải quyết vấn đề trong CI/CDCác runner tự động như GitHub Actions mặc định không có SSH agent tương tác. Bạn phải đưa private key của mình vào dưới dạng một secret. Đối với GitHub Actions, action webfactory/ssh-agent là tiêu chuẩn của ngành cho nhiệm vụ này.

- name: Setup SSH Keys
  uses: webfactory/ssh-agent@v0.5.4
  with:
    ssh-private-key: ${{ secrets.MY_TERRAFORM_DEPLOY_KEY }}

Action này sẽ điền giá trị cho biến môi trường SSH_AUTH_SOCK. Khi Terraform chạy git clone, nó sẽ tự động tìm thấy key đã tải và xác thực thành công.

Xác minh và Dọn dẹpSau khi sửa lỗi quyền truy cập hoặc agent, hãy xóa bỏ các lần thử thất bại trước đó trước khi thử lại. Terraform đôi khi để lại các thư mục dở dang có thể gây cản trở quá trình khởi tạo sạch.

# Xóa bộ nhớ đệm module cục bộ
rm -rf .terraform/modules

# Chạy lại lệnh init
terraform init

Thành công sẽ hiển thị một loạt các thông báo Downloading... màu xanh mà không có bất kỳ mã thoát 128 nào.

Các thực hành tốt nhất- Hiện đại hóa các Key: Sử dụng key Ed25519 thay vì RSA. Chúng ngắn hơn, nhanh hơn và bảo mật hơn.- Logic dấu gạch chéo kép: Luôn sử dụng // nếu module của bạn nằm trong thư mục con. Đây là lỗi cú pháp phổ biến nhất trong Terraform.- Kiểm tra Deployment Keys: Nếu bạn sử dụng "Deploy Keys" cho các kho lưu trữ cụ thể, hãy đảm bảo chúng có quyền đọc cần thiết.- Tránh HTTPS: Hãy trung thành với SSH cho các module riêng tư trong CI/CD. HTTPS thường yêu cầu nhập mật khẩu tương tác, điều này sẽ làm treo pipeline của bạn.