Tạo Upstream

Upstream đại diện cho một nhóm backend target (host và port của các instance backend). API Gateway cân bằng tải request giữa các target này, theo cấu hình kết nối, timeout và health check của Upstream.

Upstream được các module khác tham chiếu tới:

Module	Cách dùng Upstream
Route	Backend Target là Via Upstream: Route trỏ trực tiếp tới Upstream.
Service	Mục Upstream Binding: Service liên kết tới đúng 1 Upstream, các Route Via Service kế thừa Upstream này.

mẹo

Bạn cũng có thể tạo Upstream ngay trong màn hình tạo Route (+ Create new Upstream) hoặc tạo Service (+ Create a new upstream), không phải thoát ra tạo trước.

Màn hình Create Upstream chia thành các mục ở thanh điều hướng bên trái: Basic Information → Target → Connection Configuration (gồm Scheme, Load Balancing, Pass Host, Retry & Timeout, Keepalive Pool, TLS Certificate) → Health Checks → Review. Hai mục Basic Information và Target là bắt buộc, nút Create chỉ bật khi cả 2 mục đã hợp lệ. Các mục còn lại đều có giá trị mặc định.

Bạn có thể nhập Target thủ công, hoặc lấy tự động từ server list của một API trong API Catalog.

Tạo Upstream thủ công

Bước 1Nhấn Create Upstream để mở màn hình Create Upstream

1 / 7

Nhấn vào ảnh để phóng to.

Để tạo Upstream thủ công, bạn thực hiện các bước sau:

1. Chọn API Gateway → Upstream ở menu bên trái, chọn API Gateway ở góc trên bên phải, rồi nhấn Create Upstream.

2. Nhập các thông tin sau tại mục Basic Information:

Field	Bắt buộc	Mô tả
Name	Y	Tên Upstream, hiển thị ở danh sách và dùng để chọn Upstream ở màn hình Route và Service. Bắt đầu bằng chữ cái, chỉ gồm chữ a-z, số 0-9, _ và -. Tên không được trùng với Upstream khác trong cùng API Gateway.
Description	N	Mục đích của Upstream, ví dụ backend nào, môi trường nào, để người khác dễ hiểu khi xem lại.

3. Chọn mục Target, khai báo các instance backend nhận traffic:

Field	Bắt buộc	Mô tả
Target Address	Y	IP hoặc hostname của một instance backend, ví dụ api.gravitee.io. Mỗi dòng là một target trong vòng cân bằng tải.
Port	Y	Cổng của backend, từ 1 đến 65535.
Weight	Y	Trọng số của target, từ 0 đến 65535, mặc định 1. Target có Weight lớn hơn nhận nhiều traffic hơn. Đặt 0 để tạm rút target khỏi vòng cân bằng tải mà không phải xóa, ví dụ khi bảo trì một backend.

Nhấn Add Target để thêm target khi backend có nhiều instance, nhấn × ở cuối dòng để xóa target. Upstream phải còn ít nhất 1 target.

4. Chọn lần lượt các mục con của Connection Configuration nếu cần tùy chỉnh cách API Gateway kết nối tới các target. Mọi field đều có giá trị mặc định, bạn có thể bỏ qua bước này.

Scheme: giao thức giữa API Gateway và Upstream, mặc định HTTP.

Giá trị	Dùng khi
HTTP / HTTPS	Backend là REST API. Chọn HTTPS khi API Gateway cần kết nối TLS tới backend.
gRPC / gRPCs	Backend là service gRPC chạy trên HTTP/2. gRPCs là gRPC qua TLS.

Load Balancing: thuật toán chọn target nhận từng request.

Giá trị	Dùng khi
Round Robin (mặc định)	Chia lần lượt theo Weight giữa các target. Phù hợp khi các target độc lập, không cần giữ một client ở cố định một target.
CHash	Consistent Hashing: cùng một client luôn tới cùng một target. Phù hợp khi backend cần cache hoặc giữ session.
EWMA	Ưu tiên target có độ trễ trung bình thấp nhất, tự tránh target đang phản hồi chậm.
Least conn	Chọn target đang có ít kết nối nhất. Phù hợp khi thời gian xử lý các request chênh lệch nhau.

Pass Host: giá trị Host header khi API Gateway chuyển request tới Upstream.

Giá trị	Ý nghĩa
Pass (mặc định)	Giữ nguyên Host header từ request của client.
Node	Dùng domain hoặc IP của target làm Host header.
Rewrite	Dùng host tùy chỉnh. Khi chọn giá trị này, field Upstream Host hiện ra và bắt buộc nhập.

Retry & Timeout: thử lại và thời gian chờ khi gọi tới target.

Field	Bắt buộc	Mô tả
Retries	N	Số lần API Gateway thử sang target khác khi request tới một target thất bại. Mặc định 3.
Retry Timeout (s)	N	Tổng thời gian tối đa cho các lần thử lại. Mặc định 5.
Connect Timeout (s)	N	Thời gian tối đa để kết nối tới target. Mặc định 60.
Send Timeout (s)	N	Thời gian tối đa để gửi xong request tới target. Mặc định 60.
Read Timeout (s)	N	Thời gian tối đa chờ response từ target, là thời gian client phải chờ khi backend xử lý chậm. Mặc định 60.

ghi chú

Route cũng có mục Timeout riêng. Xem Tạo Route.

Keepalive Pool: giữ và dùng lại kết nối tới target, giảm chi phí mở kết nối mới.

Field	Bắt buộc	Mô tả
Size	N	Số kết nối rảnh tối đa được giữ lại để dùng lại. Mặc định 320.
Idle Timeout (s)	N	Thời gian giữ một kết nối rảnh trước khi đóng. Mặc định 60.
Requests	N	Số request tối đa trên một kết nối trước khi thay kết nối mới. Mặc định 1000.

TLS Certificate: xác thực TLS khi API Gateway kết nối tới Upstream. Chỉ có tác dụng khi Scheme là HTTPS hoặc gRPCs.

Field	Bắt buộc	Mô tả
Verify Upstream Cert	N	Bật để API Gateway kiểm tra chứng chỉ TLS của backend, chống giả mạo. Mặc định Disable.
Client Cert	N	Chứng chỉ public dạng PEM mà API Gateway gửi cho backend khi dùng mutual TLS (mTLS).
Client Key	N	Private key dạng PEM đi kèm Client Cert.

5. Chọn mục Health Checks nếu muốn API Gateway tự phát hiện target lỗi và tạm loại khỏi vòng cân bằng tải. Có 2 cơ chế độc lập, cả hai mặc định tắt.

Khi bật Active checks: API Gateway định kỳ gửi request kiểm tra (probe) tới từng target. Target lỗi quá ngưỡng bị loại khỏi vòng cân bằng tải, khi kiểm tra lại thấy ổn thì được đưa trở lại.

Field	Bắt buộc	Mô tả
Type	N	Giao thức gửi probe: HTTP hoặc HTTPs. Mặc định HTTP.
HTTPs Verify Certificate	N	Kiểm tra chứng chỉ TLS khi probe bằng HTTPs. Mặc định Disable.
Timeout (s)	N	Thời gian chờ tối đa cho mỗi probe. Mặc định 1.
Concurrency	N	Số probe gửi đồng thời. Mặc định 10.
Host, Port, HTTP Path	N	Địa chỉ và đường dẫn nhận probe. HTTP Path mặc định /.
Healthy Status: Interval, Successes	N	Chu kỳ probe (giây) và số lần probe thành công liên tiếp để coi target là khỏe. Mặc định 1 và 2.
Unhealthy Status: Interval, HTTP Failures	N	Chu kỳ probe (giây) và số lần probe lỗi để coi target là lỗi. Mặc định 1 và 5.

Khi bật Passive checks: API Gateway đánh giá target dựa trên chính traffic thật đang đi qua, không gửi thêm request kiểm tra.

Field	Bắt buộc	Mô tả
Healthy Successes	N	Số response thành công để coi target là khỏe.
Unhealthy HTTP Failures	N	Số lỗi HTTP để coi target là lỗi.
Unhealthy TCP Failures	N	Số lỗi TCP để coi target là lỗi.

6. Chọn mục Review để kiểm tra lại toàn bộ cấu hình. Mục nào để mặc định hiển thị Using defaults., Health Checks chưa bật hiển thị Disabled. Muốn sửa thì chọn lại mục tương ứng.

7. Nhấn Create để hoàn tất.

Thông báo Upstream created successfully hiển thị, hệ thống đưa bạn về màn hình Upstream và Upstream mới nằm ở đầu danh sách.

Tạo Upstream từ API Catalog

Dùng khi API đã được đăng ký trong API Catalog kèm spec có khai báo server. Hệ thống điền sẵn Target từ server list của API, bạn không phải gõ tay.

Bước 2Nhấn Create Upstream from API Catalog, form Select API Catalog mở ra

1 / 5

Nhấn vào ảnh để phóng to.

Để tạo Upstream từ API Catalog, bạn thực hiện các bước sau:

1. Chọn API Gateway → Upstream ở menu bên trái, chọn API Gateway ở góc trên bên phải, rồi nhấn Create Upstream.

2. Nhấn Create Upstream from API Catalog. Form Select API Catalog mở ra, liệt kê các API trong catalog kèm số server và địa chỉ server khai báo trong spec. Nhập từ khóa vào ô Search API catalog để tìm nhanh.

3. Chọn một API. Form tự đóng, mục Target được điền sẵn từ server list của API, Scheme được tự chọn theo giao thức của server URL (ví dụ server https://... thì Scheme là HTTPS). Phía trên hiển thị dòng Prefilled from API Catalog kèm tên API, số target và 2 nút:

• Change selection: chọn API khác.
• Clear & start blank: bỏ dữ liệu điền sẵn, nhập tay lại từ đầu.

cảnh báo

Target Address được điền nguyên văn từ server URL trong spec. Nếu spec khai báo server dạng đường dẫn tương đối (ví dụ /api/v3 như ảnh trên) thay vì URL đầy đủ, bạn cần sửa Target Address thành host của backend. Nên chọn API có server dạng URL đầy đủ (https://host:port).

4. Nhập Basic Information và tùy chỉnh các mục khác nếu cần, giống Bước 2–5 của cách tạo thủ công.

5. Chọn mục Review để kiểm tra, rồi nhấn Create.

Lỗi thường gặp

Lỗi	Nguyên nhân	Cách xử lý
Không tạo được, báo trùng tên	Đã có Upstream cùng tên trong API Gateway này	Đặt tên khác.
Nút Create không bật	Chưa nhập Name, hoặc chưa có target hợp lệ (mục có biểu tượng ⓘ đỏ)	Mở mục có biểu tượng ⓘ và nhập đủ field bắt buộc.

Bước tiếp theo

• Xem thông tin Upstream
• Tạo Route với Via Upstream
• Tạo Service liên kết tới Upstream
• Chỉnh sửa Upstream