Plugin Proxy Rewrite

Plugin Proxy Rewrite (tên kỹ thuật proxy-rewrite, nhóm Transformation) viết lại thông tin request trước khi API Gateway chuyển tới backend: đổi Host header, đổi đường dẫn (path / URI), đổi HTTP method, hoặc thêm / sửa / xóa header.

ghi chú

Proxy Rewrite không phải plugin bảo mật và không chặn request nào. Plugin chỉ biến đổi request đã hợp lệ, sau khi request đã qua các bước xử lý khác như xác thực, giới hạn request.

Trường hợp sử dụng

Plugin Proxy Rewrite phù hợp khi URI, host, method hoặc header mà client gửi tới API Gateway khác với định dạng backend yêu cầu.

Các trường hợp điển hình:

• API Gateway công bố path /v1/users nhưng backend chỉ nhận /internal/users: dùng uri hoặc regex_uri để viết lại path.
• Backend yêu cầu Host header nội bộ, khác với domain public mà client gọi: dùng host.
• Backend cũ chỉ nhận một method cố định, ví dụ POST: dùng method để chuyển mọi request sang method đó.
• Chuyển tên Consumer đã xác thực xuống backend qua header tùy biến, đồng thời xóa header chứa API key gốc: kết hợp headers.set với headers.remove.

Tạo plugin Proxy Rewrite

Để tạo plugin Proxy Rewrite, bạn thực hiện các bước sau:

1. Chọn API Gateway → Plugin ở menu bên trái, chọn API Gateway ở góc trên bên phải, nhấn New plugin, rồi chọn Proxy Rewrite trong popup Add plugin. Bạn cũng có thể thêm từ tab Plugins của Route / Service, xem Thêm Plugin.

2. Nhập Display Name tại mục Basic Information. Xem Basic Information.

3. Chọn mục Configuration. Form hiển thị sẵn cả 8 thuộc tính nhưng tất cả đang trống. Chữ màu xám trong ô (iresty.com, /get, ^/rewrite-regex/(.*), /$1) chỉ là gợi ý nhập liệu, nên JSON ban đầu là {}. Plugin không có thuộc tính bắt buộc và không có Quick Start Templates: nhập thuộc tính nào thì thuộc tính đó xuất hiện trong JSON.

Attribute	Bắt buộc	Mô tả
host	N	Host header mới gửi tới backend, thay cho Host header gốc của client. Phải là tên miền hợp lệ.
method	N	Đổi HTTP method của request trước khi chuyển tới backend. Để Keep original (mặc định) để giữ nguyên method gốc.
uri	N	Đường dẫn mới cố định gửi tới backend, hỗ trợ biến NGINX như $arg_name. Phải bắt đầu bằng /. Khi có cả uri và regex_uri, uri được ưu tiên.
regex_uri	N	Cặp [pattern, replacement] viết lại path bằng regex, dùng khi path mới cần suy ra từ path gốc. Khớp pattern thì chuyển theo replacement, không khớp thì giữ nguyên path gốc. $1, $2… tham chiếu nhóm bắt được. Nhấn + Add để thêm cặp, tổng số dòng có giá trị phải là số chẵn.
use_real_request_uri_unsafe	N	Dùng nguyên URI gốc của client, bỏ qua bước chuẩn hóa URI. Không an toàn, chỉ bật khi hiểu rõ rủi ro bảo mật.
headers.add	N	Thêm header vào request. Header cùng tên đã có vẫn được giữ, không bị ghi đè.
headers.set	N	Ghi đè giá trị header, chưa có thì thêm mới. Muốn đổi Host thì dùng thuộc tính host, không set header Host ở đây.
headers.remove	N	Xóa header khỏi request trước khi chuyển tới backend, chỉ cần tên header.

Khi cấu hình cả 3 nhóm header, thứ tự xử lý là add → remove → set.

ghi chú

Trong JSON, regex_uri là một mảng phẳng, các phần tử đi theo cặp [pattern, replacement]. 3 nhóm header nằm trong object headers: add và set là object dạng {"tên-header": "giá-trị"}, remove là mảng tên header.

4. Chọn mục Scope, chọn Global hoặc Scoped rồi gán Route / Service cần áp dụng. Xem Scope.

5. Nhấn Create. Thông báo Plugin created successfully hiển thị và plugin xuất hiện trong danh sách với cột Applied to đúng phạm vi đã chọn.

Cấu hình mẫu

4 cấu hình dưới đây ứng với 4 trường hợp ở mục Trường hợp sử dụng.

Chỉ đổi Host header, giữ nguyên path client gọi:

{
  "host": "backend.internal"
}

Bỏ tiền tố path trước khi tới backend: client gọi /v1/users/42, backend nhận /users/42:

{
  "regex_uri": [
    "^/v1/(.*)",
    "/$1"
  ]
}

Đổi hẳn path sang một giá trị cố định và ép method (backend cũ chỉ nhận POST). Khi khai cả uri và regex_uri thì uri được ưu tiên, nên thường chỉ dùng một trong hai:

{
  "uri": "/internal/users",
  "method": "POST"
}

Chuyển tên Consumer đã xác thực xuống backend qua header tùy biến, đồng thời xóa header chứa API key gốc:

{
  "headers": {
    "set": {
      "X-Consumer-Name": "$consumer_name",
      "X-Forwarded-Client-IP": "$remote_addr"
    },
    "remove": [
      "X-API-Key"
    ]
  }
}

ghi chú

Giá trị bắt đầu bằng $ là biến NGINX, được thay bằng giá trị thật khi request đi qua API Gateway. $consumer_name chỉ có giá trị khi Route / Service đã có plugin xác thực (như JWT Auth) chạy trước, nếu không header sẽ rỗng.

Lỗi thường gặp

Form kiểm tra và báo lỗi ngay khi nhập:

Lỗi	Nguyên nhân	Cách xử lý
host báo lỗi	Giá trị không phải tên miền hợp lệ	Nhập đúng định dạng tên miền, ví dụ backend.internal.
uri báo lỗi	Giá trị không bắt đầu bằng /	Thêm / ở đầu, ví dụ /internal/users.
regex_uri báo lỗi	Số dòng có giá trị là số lẻ, thiếu replacement cho một pattern	Nhập đủ từng cặp pattern / replacement.
Tên header báo lỗi	Tên header chứa ký tự :	Bỏ ký tự : khỏi tên header.

Bước tiếp theo

• Tổng quan Plugin
• Xem thông tin Plugin