API Gateway là gì? Cài đặt Ocelot trong ASP.NET Core – Chặng đường trong Lộ trình .NET

Bạn có bốn service và client đang gọi thẳng cả bốn. Sáu tháng sau là mười hai service, ba client, và mỗi client tự xử lý auth, retry, timeout theo cách riêng. Đó là lúc người ta thêm API Gateway — hoặc là lúc người ta thêm một điểm chết mới vào hệ thống mà không ai vận hành được. Bài này nói rõ gateway làm gì, cách dựng bằng Ocelot 25.0.2 trong ASP.NET Core, khi nào nên dùng YARP 2.3.0 thay thế, và khi nào đúng là không nên thêm gateway.

Cập nhật 2026

  • Ocelot 25.0.2 vẫn là lựa chọn thuần .NET, cấu hình JSON, do cộng đồng bảo trì; tài liệu cũ dùng ReRoutes, nay là Routes.
  • YARP 2.3.0 do Microsoft bảo trì, là mặc định an toàn hơn cho gateway mới — nhưng nó là reverse proxy, không phải gateway đóng gói sẵn mọi tính năng.
  • app.UseOcelot().Wait() trong bài cũ là anti-pattern; API hiện tại là await app.UseOcelot().
  • Rate limiting và output caching đã là middleware first-class của ASP.NET Core 10, nên đẩy các concern đó xuống gateway bằng AddRateLimiter thay vì tin hoàn toàn vào config của proxy.

Gateway thực sự làm gì

Một gateway tốt là một lớp edge mỏng, có nhiệm vụ rõ ràng. Danh sách dưới đây cũng là danh sách để bạn tự hỏi “service của tôi có cần việc này ở tầng edge không”:

  • Routing: map /catalog/* tới catalog service, /orders/* tới order service. Đây là lý do tồn tại cơ bản nhất.
  • Authn/Authz ở edge: xác thực JWT một lần, chặn request không hợp lệ trước khi nó chạm service nội bộ. Service vẫn phải kiểm tra quyền nghiệp vụ của chính nó — gateway không thay thế authorization theo resource.
  • Rate limit, request size, timeout: chặn tải xấu ở cửa ngõ thay vì để mỗi service tự phòng thủ.
  • Retry/circuit breaker: với lỗi tạm thời của downstream, nhưng chỉ cho request idempotent. Retry một POST tạo đơn hàng là cách tạo đơn trùng.
  • Aggregation: gộp vài lời gọi thành một response cho client. Đây là ranh giới với BFF, sẽ nói ở dưới.
  • Protocol translation: client REST, backend gRPC — gateway làm cầu.
  • Observability: một nơi phát trace id, đo latency theo route, log 4xx/5xx theo service đích.

Điều gateway không làm: không sửa nghiệp vụ, không giữ state của client, không “vá” API xấu bằng cách biến đổi payload phức tạp. Càng nhiều logic trong gateway, càng khó test và càng dễ thành monolith thứ hai.

Dựng gateway với Ocelot 25.0.2

Ocelot đọc route từ JSON và chạy như middleware trong pipeline ASP.NET Core. Project gateway là một web app riêng:

dotnet new web -n ApiGateway
dotnet add ApiGateway package Ocelot --version 25.0.2
// File: src/ApiGateway/Program.cs
using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile("ocelot.json", optional: false, reloadOnChange: true);
builder.Services.AddOcelot(builder.Configuration);
builder.WebHost.ConfigureKestrel(o => o.Limits.MaxRequestBodySize = 10 * 1024 * 1024);

var app = builder.Build();

await app.UseOcelot();
app.Run();

UseOcelot là async vì nó nạp và validate cấu hình; await ở top-level statement là đúng, .Wait() chỉ tổng hợp lại một lỗi khó đọc.

{
  "Routes": [
    {
      "UpstreamHttpMethod": [ "GET", "POST" ],
      "UpstreamPathTemplate": "/catalog/{everything}",
      "DownstreamPathTemplate": "/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        { "Host": "catalog-1", "Port": 8080 },
        { "Host": "catalog-2", "Port": 8080 }
      ],
      "LoadBalancerOptions": { "Type": "RoundRobin" },
      "QoSOptions": {
        "ExceptionsAllowedBeforeBreaking": 3,
        "DurationOfBreak": 5000,
        "TimeoutValue": 10000
      }
    },
    {
      "UpstreamHttpMethod": [ "GET" ],
      "UpstreamPathTemplate": "/orders/{orderId}",
      "DownstreamPathTemplate": "/api/orders/{orderId}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [ { "Host": "orders", "Port": 8080 } ],
      "Timeout": 5000
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://api.example.com"
  }
}

Ba thứ trong file này quyết định hành vi production nhiều hơn phần còn lại: LoadBalancerOptions chỉ có ý nghĩa khi bạn khai báo nhiều host và các host đó thực sự độc lập; QoSOptions là circuit breaker của Ocelot (sau N lần lỗi thì mở mạch trong DurationOfBreak ms); và Timeout phải nhỏ hơn timeout của ingress, nếu không client sẽ thấy 504 từ ingress trong khi log gateway không ghi gì.

Reload cấu hình: Ocelot hỗ trợ cấu hình động qua reloadOnChange khi nguồn là file, và qua config provider (Consul, Kubernetes) khi bạn dùng các package provider tương ứng. Đây là con dao hai lưỡi: sửa route trên production không cần deploy là tiện, nhưng cũng là thay đổi không qua review. Nếu team bạn cần audit, hãy giữ route trong git và deploy như code.

Auth ở gateway: đừng nhân đôi logic

Cách làm đúng là gateway xác thực token, rồi chuyển danh tính xuống downstream qua header nội bộ có chữ ký, và service nội bộ tin header đó chỉ khi request đến từ mạng nội bộ. Cách làm sai — và rất phổ biến — là để service tự gọi lại auth service cho mỗi request, hoặc tệ hơn, để gateway chuyển nguyên Authorization header xuống và mỗi service tự parse JWT với secret khác nhau.

Ocelot có AuthenticationOptions ở cấp route và global để chỉ định authentication provider; bạn cấu hình JWT bearer trong DI như một authentication scheme bình thường của ASP.NET Core. Điều cần nhớ: Ocelot chỉ quyết định “request này có được đi tiếp không”. Phân quyền theo tài nguyên (user này có được xem đơn hàng của người khác không) vẫn thuộc về service.

Rate limit và giới hạn kích thước

// File: src/ApiGateway/Program.cs — trước app.UseOcelot()
using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(o =>
{
    o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
    o.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(ctx =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: ctx.Connection.RemoteIpAddress?.ToString() ?? "unknown",
            factory: _ => new FixedWindowRateLimiterOptions
            {
                PermitLimit = 100,
                Window = TimeSpan.FromMinutes(1),
                QueueLimit = 0
            }));
});

Đặt app.UseRateLimiter() trước UseOcelot để request bị chặn không đi vào proxy. Lưu ý: RemoteIpAddress sau ingress là IP của ingress, không phải của client — phải bật UseForwardedHeaders với KnownProxies đúng, nếu không mọi client sẽ chung một partition và bạn tự DDoS chính mình.

Bảo mật ở tầng gateway

Gateway là nơi dễ tạo lỗ hổng nhất vì nó là chỗ duy nhất tin được cấu hình. Bốn việc bắt buộc:

  • Header stripping: bỏ các header do client tự đặt mà downstream tin, đặc biệt X-Forwarded-For, X-Forwarded-Proto, X-User-Id, X-Internal-Token. Chỉ ingress được phép ghi các header này.
  • Không forward hop-by-hop headers: Connection, Transfer-Encoding, Upgrade (trừ khi bạn cố ý proxy WebSocket).
  • CORS tường minh: liệt kê origin thật, không dùng * cùng credentials. CORS ở gateway, không rải ở từng service — nếu không bạn sẽ có ba bộ policy khác nhau.
  • Giới hạn body và timeout: Kestrel MaxRequestBodySize như trên, cộng timeout downstream. Gateway không có giới hạn là một cách tải file 2 GB vào bộ nhớ service.

Thêm một điểm ít được nói: đừng để gateway trả về stack trace hay header Server của Kestrel. Production cần ProblemDetails thống nhất, không cần lộ phiên bản hạ tầng.

YARP 2.3.0: lựa chọn của Microsoft

YARP là reverse proxy do team ASP.NET Core bảo trì, dùng chính HttpClient/Kestrel pipeline, hỗ trợ HTTP/2, gRPC, WebSocket. Nó không có aggregation, không có “QoS options” kiểu Ocelot — bạn ghép middleware ASP.NET Core để có những thứ đó. Đổi lại bạn có API ổn định, hiệu năng tốt và không phụ thuộc một maintainer duy nhất.

// File: src/ApiGateway/appsettings.json
{
  "ReverseProxy": {
    "Routes": {
      "catalog": {
        "ClusterId": "catalog-cluster",
        "Match": { "Path": "/catalog/{**catch-all}" }
      }
    },
    "Clusters": {
      "catalog-cluster": {
        "Destinations": {
          "one": { "Address": "http://catalog-1:8080/" },
          "two": { "Address": "http://catalog-2:8080/" }
        }
      }
    }
  }
}
// File: src/ApiGateway/Program.cs
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();
app.MapReverseProxy();
app.Run();

Với YARP, thứ tự middleware là của bạn: auth, rate limit, forwarded headers, rồi MapReverseProxy. Ưu điểm là không có “magic” nào bạn không kiểm soát; nhược điểm là bạn phải tự viết transform nếu cần đổi path/header phức tạp, và không có sẵn aggregation.

Service discovery: tĩnh, Consul hay Kubernetes

Câu hỏi thực tế không phải “Ocelot có hỗ trợ Consul không” mà là “bạn có thực sự cần discovery không”. Trên Kubernetes, một Service headless đã cho bạn DNS trỏ tới các pod; http://catalog:8080 là đủ và ổn định hơn mọi registry. Discovery chỉ đáng thêm khi bạn chạy VM/bare-metal, hoặc có nhiều cluster và cần routing theo metadata.

  • Consul: dùng Ocelot.Provider.Consul cho Ocelot, hoặc service discovery của Microsoft.Extensions.ServiceDiscovery (Aspire) cho YARP.
  • Kubernetes: dùng Ocelot.Provider.Kubernetes, hoặc chỉ cần DNS.
  • Tĩnh: danh sách host trong config, đơn giản nhất, và là lựa chọn đúng cho phần lớn hệ thống dưới 20 service.

Discovery có cái bẫy riêng: khi registry trả về instance đã chết, gateway vẫn route tới đó cho đến khi health check loại bỏ. Nếu bạn không cấu hình health check và circuit breaker, discovery làm tăng tỉ lệ lỗi so với danh sách tĩnh.

BFF và gateway khác nhau ở đâu

Gateway là một lớp dùng chung cho mọi client. BFF (Backend For Frontend) là một lớp riêng cho từng loại client: web cần session cookie và aggregate 3 service thành một màn hình; mobile cần payload nhỏ hơn, ít round trip hơn; partner cần API ổn định và rate limit theo hợp đồng.

Nếu bạn nhét cả ba nhu cầu vào một gateway, bạn sẽ có route với điều kiện “nếu header là mobile thì bỏ field này” — đó là logic trình bày, không phải routing. Cách phân tầng hợp lý: ingress/gateway lo auth, TLS, rate limit, routing; BFF lo aggregate và shaping cho từng client; service lo nghiệp vụ. Với hệ thống nhỏ, gộp gateway và BFF làm một là chấp nhận được, miễn bạn biết mình đang gộp.

Khi nào không nên thêm gateway

  • Bạn có 1–3 service và một team. Client gọi thẳng, dùng chung một thư viện auth/retry — rẻ hơn và ít điểm chết hơn.
  • Bạn đang chạy monolith. Gateway trước monolith chỉ thêm một hop latency và một thứ phải deploy.
  • Bạn đã có API Management (Azure APIM, Kong, Envoy Gateway). Thêm Ocelot/YARP nữa là hai lớp edge, hai nơi cấu hình auth.
  • Nhu cầu chính là “đổi tên endpoint” hoặc “che internal URL”. DNS + ingress của cloud làm được, không cần app gateway.

Và nếu bạn thêm gateway, hãy tính chi phí thật: nó là một service phải có health check, alerting, capacity planning, và một on-call rotation. Một gateway không được giám sát sẽ âm thầm trả 502 cho toàn bộ sản phẩm.

Observability: thứ quyết định gateway có dùng được không

Bật OpenTelemetry trong gateway và propagate traceparent xuống downstream; nếu không, một request chậm sẽ hiện thành một span ở gateway và một span rời rạc ở service, không nối được. Ghi log theo route template chứ không theo URL thật (tránh cardinality nổ), đo ba chỉ số: request rate theo route, p95 latency theo downstream, tỉ lệ 5xx theo service đích. Thêm health check cho từng cluster để circuit breaker có dữ liệu.

Bảng quyết định

Tiêu chí Ocelot 25.0.2 YARP 2.3.0
Bảo trì Cộng đồng, mature Microsoft, nhịp release đều
Cấu hình JSON route + provider, có reload JSON hoặc IProxyConfigProvider trong code
Tính năng sẵn Aggregation, QoS/circuit breaker, load balancing Proxy thuần; ghép middleware để có phần còn lại
Hợp với Team cần gateway “có sẵn”, ít code Team muốn kiểm soát pipeline, dùng chung hệ sinh thái ASP.NET Core

Nhìn tới 2027

Xu hướng rõ ràng là đẩy edge xuống hạ tầng: Kubernetes Gateway API, Envoy, hoặc API Management của cloud, còn app chỉ giữ BFF. Với .NET, YARP 2.x nhiều khả năng tiếp tục là nền tảng được Microsoft đầu tư; Ocelot vẫn ổn cho hệ thống đang chạy nhưng sẽ ít được chọn cho dự án mới. .NET 11 (GA tháng 11/2026, STS) không thay đổi gì lớn ở tầng proxy.

Checklist trước khi dựng gateway

  • Liệt kê route cần expose; nếu dưới 5 route và một client, cân nhắc không làm gateway.
  • Quyết định auth kết thúc ở đâu, và service nội bộ tin danh tính qua kênh nào.
  • Đặt timeout gateway nhỏ hơn ingress, và circuit breaker theo từng cluster.
  • Chặn body size, rate limit theo IP sau forwarded headers đúng.
  • Bật trace propagation ngay từ ngày đầu, không phải sau sự cố đầu tiên.
  • Viết runbook: gateway chết thì ai gọi, rollback route thế nào.

Đọc tiếp trong series: