部署Nginx Plus作為API網(wǎng)關(guān)：Nginx
了解著名的Nginx服務(wù)器(微服務(wù)必不可少的東西)如何用作API網(wǎng)關(guān)。
現(xiàn)代應(yīng)用程序體系結(jié)構(gòu)的核心是HTTP API。 HTTP使應(yīng)用程序能夠快速構(gòu)建并輕松維護(hù)。無(wú)論應(yīng)用程序的規(guī)模如何，HTTP API都提供了一個(gè)通用接口，從單用途微服務(wù)到無(wú)所不包的整體。通過(guò)使用HTTP，支持超大規(guī)模Internet屬性的Web應(yīng)用程序交付的進(jìn)步也可用于提供可靠和高性能的API交付。
有關(guān)API網(wǎng)關(guān)對(duì)微服務(wù)應(yīng)用程序重要性的精彩介紹，請(qǐng)參閱我們博客上的構(gòu)建微服務(wù)：使用API網(wǎng)關(guān)。
作為領(lǐng)先的高性能，輕量級(jí)反向代理和負(fù)載均衡器，NGINX Plus具有處理API流量所需的高級(jí)HTTP處理功能。這使得NGINX Plus成為構(gòu)建API網(wǎng)關(guān)的理想平臺(tái)。在這篇博文中，我們描述了許多常見(jiàn)的API網(wǎng)關(guān)用例，并展示了如何配置NGINX Plus以便以高效，可擴(kuò)展且易于維護(hù)的方式處理它們。我們描述了一個(gè)完整的配置，它可以構(gòu)成生產(chǎn)部署的基礎(chǔ)。
注意：除非另有說(shuō)明，否則本文中的所有信息均適用于NGINX Plus和NGINX開(kāi)源。
介紹Warehouse API
API網(wǎng)關(guān)的主要功能是為多個(gè)API提供單一，一致的入口點(diǎn)，無(wú)論它們?cè)诤蠖巳绾螌?shí)現(xiàn)或部署。并非所有API都是微服務(wù)應(yīng)用程序。我們的API網(wǎng)關(guān)需要管理現(xiàn)有的API，單塊和正在部分過(guò)渡到微服務(wù)的應(yīng)用程序。
在這篇博文中，我們引用了一個(gè)假設(shè)的庫(kù)存管理API，即“倉(cāng)庫(kù)API”。我們使用示例配置代碼來(lái)說(shuō)明不同的用例。 Warehouse API是一個(gè)RESTful API，它使用JSON請(qǐng)求并生成JSON響應(yīng)。但是，當(dāng)部署為API網(wǎng)關(guān)時(shí)，使用JSON不是NGINX Plus的限制或要求; NGINX Plus與API本身使用的架構(gòu)風(fēng)格和數(shù)據(jù)格式無(wú)關(guān)。
Warehouse API實(shí)現(xiàn)為離散微服務(wù)的集合，并作為單個(gè)API發(fā)布。庫(kù)存和定價(jià)資源作為單獨(dú)的服務(wù)實(shí)施，并部署到不同的后端。所以API的路徑結(jié)構(gòu)是：
- api └── warehouse
- ├── inventory
- └── pricing
例如，要查詢當(dāng)前倉(cāng)庫(kù)庫(kù)存，客戶端應(yīng)用程序會(huì)向/ api / warehouse / inventory發(fā)出HTTP GET請(qǐng)求。
組織NGINX配置
使用NGINX Plus作為API網(wǎng)關(guān)的一個(gè)優(yōu)點(diǎn)是，它可以執(zhí)行該角色，同時(shí)充當(dāng)現(xiàn)有HTTP流量的反向代理，負(fù)載平衡器和Web服務(wù)器。如果NGINX Plus已經(jīng)是應(yīng)用程序交付堆棧的一部分，那么通常不需要部署單獨(dú)的API網(wǎng)關(guān)。但是，API網(wǎng)關(guān)所期望的某些默認(rèn)行為與基于瀏覽器的流量的預(yù)期不同。出于這個(gè)原因，我們將API網(wǎng)關(guān)配置與基于瀏覽器的流量的任何現(xiàn)有(或未來(lái))配置分開(kāi)。
為實(shí)現(xiàn)這種分離，我們創(chuàng)建了一個(gè)支持多用途NGINX Plus實(shí)例的配置布局，并為通過(guò)CI / CD管道自動(dòng)配置部署提供了便利的結(jié)構(gòu)。 / etc / nginx下的結(jié)果目錄結(jié)構(gòu)如下所示。
- etc/ └── nginx/
- ├── api_conf.d/ ....................................... Subdirectory for per-API configuration
- │ └── warehouse_api.conf ...... Definition and policy of the Warehouse API
- ├── api_backends.conf ..................... The backend services (upstreams)
- ├── api_gateway.conf ........................ Top-level configuration for the API gateway server
- ├── api_json_errors.conf ............ HTTP error responses in JSON format
- ├── conf.d/
- │ ├── ...
- │ └── existing_apps.conf
- └── nginx.conf
所有API網(wǎng)關(guān)配置的目錄和文件名都以api_為前綴。這些文件和目錄中的每一個(gè)都啟用API網(wǎng)關(guān)的不同特性和功能，并在下面詳細(xì)說(shuō)明。
定義頂級(jí)API網(wǎng)關(guān)
所有NGINX配置都以主配置文件nginx.conf開(kāi)頭。要讀入API網(wǎng)關(guān)配置，我們?cè)趎ginx.conf的http塊中添加一個(gè)指令，該指令引用包含網(wǎng)關(guān)配置的文件api_gateway.conf(下面的第28行)。請(qǐng)注意，默認(rèn)的nginx.conf文件使用include偽指令從conf.d子目錄中引入基于瀏覽器的HTTP配置(第29行)。本博文廣泛使用include指令來(lái)提高可讀性并實(shí)現(xiàn)配置某些部分的自動(dòng)化。
- include /etc/nginx/api_gateway.conf; # All API gateway configuration
- include /etc/nginx/conf.d/*.conf; # Regular web traffic
api_gateway.conf文件定義了將NGINX Plus公開(kāi)為客戶端的API網(wǎng)關(guān)的虛擬服務(wù)器。此配置公開(kāi)API網(wǎng)關(guān)在單個(gè)入口點(diǎn)https://api.example.com/(第13行)發(fā)布的所有API，受第16到21行配置的TLS保護(hù)。請(qǐng)注意，此配置純粹是HTTPS - 沒(méi)有明文HTTP偵聽(tīng)器。我們希望API客戶端知道正確的入口點(diǎn)并默認(rèn)進(jìn)行HTTPS連接。
- log_format api_main '$remote_addr - $remote_user [$time_local] "$request"'
- '$status $body_bytes_sent "$http_referer" "$http_user_agent"'
- '"$http_x_forwarded_for" "$api_name"';
- include api_backends.conf;
- include api_keys.conf;
- server {
- set $api_name -; # Start with an undefined API name, each API will update this value
- access_log /var/log/nginx/api_access.log api_main; # Each API may also log to a separate file
- listen 443 ssl;
- server_name api.example.com;
- # TLS config
- ssl_certificate /etc/ssl/certs/api.example.com.crt;
- ssl_certificate_key /etc/ssl/private/api.example.com.key;
- ssl_session_cache shared:SSL:10m;
- ssl_session_timeout 5m;
- ssl_ciphers HIGH:!aNULL:!MD5;
- ssl_protocols TLSv1.1 TLSv1.2;
- # API definitions, one per file
- include api_conf.d/*.conf;
- # Error responses
- error_page 404 = @400; # Invalid paths are treated as bad requests
- proxy_intercept_errors on; # Do not send backend errors to the client
- include api_json_errors.conf; # API client friendly JSON error responses
- default_type application/json; # If no content-type then assume JSON
- }
此配置是靜態(tài)的 - 各個(gè)API及其后端服務(wù)的詳細(xì)信息在第24行的include偽指令引用的文件中指定。第27到30行處理日志記錄默認(rèn)值和錯(cuò)誤處理，并在響應(yīng)中討論錯(cuò)誤部分如下。
單服務(wù)與微服務(wù)API后端
一些API可以在單個(gè)后端實(shí)現(xiàn)，但是出于彈性或負(fù)載平衡的原因，我們通常期望存在多個(gè)API。使用微服務(wù)API，我們?yōu)槊總€(gè)服務(wù)定義單獨(dú)的后端;它們一起作為完整的API。在這里，我們的Warehouse API被部署為兩個(gè)獨(dú)立的服務(wù)，每個(gè)服務(wù)都有多個(gè)后端。
- upstream warehouse_inventory {
- zone inventory_service 64k;
- server 10.0.0.1:80;
- server 10.0.0.2:80;
- server 10.0.0.3:80;
- }
- upstream warehouse_pricing {
- zone pricing_service 64k;
- server 10.0.0.7:80;
- server 10.0.0.8:80;
- server 10.0.0.9:80;
- }
API網(wǎng)關(guān)發(fā)布的所有API的所有后端API服務(wù)都在api_backends.conf中定義。這里我們?cè)诿總€(gè)塊中使用多個(gè)IP地址 - 端口對(duì)來(lái)指示API代碼的部署位置，但也可以使用主機(jī)名。 NGINX Plus訂戶還可以利用動(dòng)態(tài)DNS負(fù)載平衡，自動(dòng)將新后端添加到運(yùn)行時(shí)配置中。
定義Warehouse API
配置的這一部分首先定義Warehouse API的有效URI，然后定義用于處理對(duì)Warehouse API的請(qǐng)求的公共策略。
- # API definition
- #
- location /api/warehouse/inventory {
- set $upstream warehouse_inventory;
- rewrite ^ /_warehouse last;
- }
- location /api/warehouse/pricing {
- set $upstream warehouse_pricing;
- rewrite ^ /_warehouse last;
- }
- # Policy section
- #
- location = /_warehouse {
- internal;
- set $api_name "Warehouse";
- # Policy configuration here (authentication, rate limiting, logging, more...)
- proxy_pass http://$upstream$request_uri;
- }
Warehouse API定義了許多塊。 NGINX Plus具有高效靈活的系統(tǒng)，可將請(qǐng)求URI與配置的一部分進(jìn)行匹配。通常，請(qǐng)求由最具體的路徑前綴匹配，并且位置指令的順序并不重要。這里，在第3行和第8行，我們定義了兩個(gè)路徑前綴。在每種情況下，$ upstream變量都設(shè)置為上游塊的名稱，該上游塊分別代表庫(kù)存和定價(jià)服務(wù)的后端API服務(wù)。
此配置的目標(biāo)是將API定義與管理API交付方式的策略分開(kāi)。為此，我們最小化了API定義部分中顯示的配置。在為每個(gè)位置確定適當(dāng)?shù)纳嫌谓M之后，我們停止處理并使用指令來(lái)查找API的策略(第10行)。
使用重寫指令將處理移至API策略部分
重寫指令的結(jié)果是NGINX Plus搜索匹配以/ _warehouse開(kāi)頭的URI的位置塊。第15行的位置塊使用=修飾符執(zhí)行完全匹配，從而加快處理速度。
在這個(gè)階段，我們的政策部分非常簡(jiǎn)單。位置塊本身標(biāo)記為第16行，這意味著客戶端無(wú)法直接向它發(fā)出請(qǐng)求。重新定義$ api_name變量以匹配API的名稱，以便它在日志文件中正確顯示。最后，請(qǐng)求被代理到API定義部分中指定的上游組，使用$ request_uri變量 - 其中包含原始請(qǐng)求URI，未經(jīng)修改。
選擇廣泛或者精確的API定義
API定義有兩種方法 - 廣泛而精確。每種API最合適的方法取決于API的安全要求以及后端服務(wù)是否需要處理無(wú)效的URI。
在warehouse_api_simple.conf中，我們通過(guò)在第3行和第8行定義URI前綴來(lái)使用Warehouse API的廣泛方法。這意味著以任一前綴開(kāi)頭的任何URI都代理到相應(yīng)的后端服務(wù)。使用基于前綴的位置匹配，對(duì)以下URI的API請(qǐng)求都是有效的：
- /api/warehouse/inventory
- /api/warehouse/inventory/
- /api/warehouse/inventory/foo
- /api/warehouse/inventoryfoo
- /api/warehouse/inventoryfoo/bar/
如果唯一的考慮是將每個(gè)請(qǐng)求代理到正確的后端服務(wù)，則廣泛的方法提供最快的處理和最緊湊的配置。另一方面，精確的方法使API網(wǎng)關(guān)能夠通過(guò)顯式定義每個(gè)可用API資源的URI路徑來(lái)理解API的完整URI空間。采用精確的方法，Warehouse API的以下配置使用精確匹配(=)和正則表達(dá)式(〜)的組合來(lái)定義每個(gè)URI。
- location = /api/warehouse/inventory { # Complete inventory
- set $upstream inventory_service;
- rewrite ^ /_warehouse last;
- }
- location ~ ^/api/warehouse/inventory/shelf/[^/]*$ { # Shelf inventory
- set $upstream inventory_service;
- rewrite ^ /_warehouse last;
- }
- location ~ ^/api/warehouse/inventory/shelf/[^/]*/box/[^/]*$ { # Box on shelf
- set $upstream inventory_service;
- rewrite ^ /_warehouse last;
- }
- location ~ ^/api/warehouse/pricing/[^/]*$ { # Price for specific item
- set $upstream pricing_service;
- rewrite ^ /_warehouse last;
- }
此配置更詳細(xì)，但更準(zhǔn)確地描述了后端服務(wù)實(shí)現(xiàn)的資源。這具有保護(hù)后端服務(wù)免于格式錯(cuò)誤的客戶端請(qǐng)求的優(yōu)點(diǎn)，代價(jià)是正常表達(dá)式匹配的一些小額外開(kāi)銷。有了這個(gè)配置，NGINX Plus接受一些URI并拒絕其他URI無(wú)效：
使用精確的API定義，現(xiàn)有的API文檔格式可以驅(qū)動(dòng)API網(wǎng)關(guān)的配置?？梢詮腛penAPI規(guī)范(以前稱為Swagger)自動(dòng)化NGINX Plus API定義。此博客文章的Gists中提供了用于此目的的示例腳本。
重寫客戶請(qǐng)求
隨著API的發(fā)展，有時(shí)會(huì)發(fā)生需要更新客戶端的重大更改。一個(gè)這樣的示例是重命名或移動(dòng)API資源。與Web瀏覽器不同，API網(wǎng)關(guān)無(wú)法向其客戶端發(fā)送命名新位置的重定向(代碼301)。幸運(yùn)的是，當(dāng)修改API客戶端不切實(shí)際時(shí)，我們可以動(dòng)態(tài)地重寫客戶端請(qǐng)求。
在下面的示例中，我們可以在第3行看到定價(jià)服務(wù)以前是作為庫(kù)存服務(wù)的一部分實(shí)現(xiàn)的：rewrite指令將對(duì)舊定價(jià)資源的請(qǐng)求轉(zhuǎn)換為新的定價(jià)服務(wù)。
- # Rewrite rules
- #
- rewrite ^/api/warehouse/inventory/item/price/(.*) /api/warehouse/pricing/$1;
- # API definition
- #
- location /api/warehouse/inventory {
- set $upstream inventory_service;
- rewrite ^(.*)$ /_warehouse$1 last;
- }
- location /api/warehouse/pricing {
- set $upstream pricing_service;
- rewrite ^(.*) /_warehouse$1 last;
- }
- # Policy section
- #
- location /_warehouse {
- internal;
- set $api_name "Warehouse";
- # Policy configuration here (authentication, rate limiting, logging, more...)
- rewrite ^/_warehouse/(.*)$ /$1 break; # Remove /_warehouse prefix
- proxy_pass http://$upstream; # Proxy the rewritten URI
- }
動(dòng)態(tài)重寫URI意味著當(dāng)我們最終在第26行代理請(qǐng)求時(shí)，我們不能再使用$ request_uri變量(正如我們?cè)趙arehouse_api_simple.conf的第21行所做的那樣)。這意味著我們需要在API定義部分的第9行和第14行使用稍微不同的重寫指令，以便在處理切換到策略部分時(shí)保留URI。
回應(yīng)錯(cuò)誤
HTTP API和基于瀏覽器的流量之間的主要區(qū)別之一是如何將錯(cuò)誤傳達(dá)給客戶端。當(dāng)NGINX Plus作為API網(wǎng)關(guān)部署時(shí)，我們將其配置為以最適合API客戶端的方式返回錯(cuò)誤。
- # Error responses
- error_page 404 = @400; # Invalid paths are treated as bad requests
- proxy_intercept_errors on; # Do not send backend errors to the client
- include api_json_errors.conf; # API client friendly JSON error responses
- default_type application/json; # If no content-type then assume JSON
頂級(jí)API網(wǎng)關(guān)配置包括一個(gè)定義如何處理錯(cuò)誤響應(yīng)的部分。
第27行的指令指定當(dāng)請(qǐng)求與任何API定義都不匹配時(shí)，NGINX Plus會(huì)返回錯(cuò)誤而不是默認(rèn)錯(cuò)誤。此(可選)行為要求API客戶端僅向API文檔中包含的有效URI發(fā)出請(qǐng)求，并防止未經(jīng)授權(quán)的客戶端發(fā)現(xiàn)通過(guò)API網(wǎng)關(guān)發(fā)布的API的URI結(jié)構(gòu)。
第28行指的是后端服務(wù)本身產(chǎn)生的錯(cuò)誤。未處理的異常可能包含我們不希望發(fā)送到客戶端的堆棧跟蹤或其他敏感數(shù)據(jù)。此配置通過(guò)向客戶端發(fā)送標(biāo)準(zhǔn)化錯(cuò)誤來(lái)進(jìn)一步提供保護(hù)。
完整的錯(cuò)誤響應(yīng)列表在第29行的include偽指令引用的單獨(dú)配置文件中定義，其前幾行如下所示。如果首選不同的錯(cuò)誤格式，并且通過(guò)更改第30行上的default_type值以匹配，則可以修改此文件。您還可以在每個(gè)API的策略部分中使用單獨(dú)的include指令來(lái)定義一組覆蓋默認(rèn)值的錯(cuò)誤響應(yīng)。
- error_page 400 = @400;
- location @400 { return 400 '{"status":400,"message":"Bad request"}\n'; }
- error_page 401 = @401;
- location @401 { return 401 '{"status":401,"message":"Unauthorized"}\n'; }
- error_page 403 = @403;
- location @403 { return 403 '{"status":403,"message":"Forbidden"}\n'; }
- error_page 404 = @404;
- location @404 { return 404 '{"status":404,"message":"Resource not found"}\n'; }
有了這種配置，客戶端對(duì)無(wú)效URI的請(qǐng)求就會(huì)收到以下響應(yīng)。
- $ curl -i https://api.example.com/foo
- HTTP/1.1 400 Bad Request
- Server: nginx/1.13.10
- Content-Type: application/json
- Content-Length: 39
- Connection: keep-alive
- {"status":400,"message":"Bad request"}
實(shí)施身份驗(yàn)證
在沒(méi)有某種形式的身份驗(yàn)證的情況下發(fā)布API以保護(hù)它們是不常見(jiàn)的。 NGINX Plus提供了幾種保護(hù)API和驗(yàn)證API客戶端的方法。有關(guān)基于IP地址的訪問(wèn)控制列表(ACL)，數(shù)字證書(shū)身份驗(yàn)證和HTTP基本身份驗(yàn)證的信息，請(qǐng)參閱文檔。在這里，我們專注于API特定的身份驗(yàn)證方法。
API密鑰身份驗(yàn)證
API密鑰是客戶端和API網(wǎng)關(guān)已知的共享密鑰。它們本質(zhì)上是作為長(zhǎng)期憑證發(fā)布給API客戶端的長(zhǎng)而復(fù)雜的密碼。創(chuàng)建API密鑰很簡(jiǎn)單 - 只需編碼一個(gè)隨機(jī)數(shù)，如本例所示。
- openssl rand -base64 18 7B5zIqmRGXmrJTFmKa99vcit
在頂級(jí)API網(wǎng)關(guān)配置文件api_gateway.conf的第6行，我們包含一個(gè)名為api_keys.conf的文件，其中包含每個(gè)API客戶端的API密鑰，由客戶端名稱或其他描述標(biāo)識(shí)。
- map $http_apikey $api_client_name {
- default "";
- "7B5zIqmRGXmrJTFmKa99vcit" "client_one";
- "QzVV6y1EmQFbbxOfRCwyJs35" "client_two";
- "mGcjH8Fv6U9y3BVF9H3Ypb9T" "client_six";
- }
API密鑰在塊中定義。 map指令有兩個(gè)參數(shù)。第一個(gè)定義了API密鑰的位置，在本例中是在$ http_apikey變量中捕獲的客戶端請(qǐng)求的apikey HTTP頭。第二個(gè)參數(shù)創(chuàng)建一個(gè)新變量($ api_client_name)并將其設(shè)置為第一個(gè)參數(shù)與鍵匹配的行上的第二個(gè)參數(shù)的值。
例如，當(dāng)客戶端提供API密鑰7B5zIqmRGXmrJTFmKa99vcit時(shí)，$ api_client_name變量設(shè)置為client_one。此變量可用于檢查經(jīng)過(guò)身份驗(yàn)證的客戶端，并包含在日志條目中以進(jìn)行更詳細(xì)的審核。
地圖塊的格式很簡(jiǎn)單，易于集成到自動(dòng)化工作流程中，從現(xiàn)有的憑證存儲(chǔ)生成api_keys.conf文件。 API密鑰身份驗(yàn)證由每個(gè)API的策略部分強(qiáng)制執(zhí)行。
- # Policy section
- #
- location = /_warehouse {
- internal;
- set $api_name "Warehouse";
- if ($http_apikey = "") {
- return 401; # Unauthorized (please authenticate)
- }
- if ($api_client_name = "") {
- return 403; # Forbidden (invalid API key)
- }
- proxy_pass http://$upstream$request_uri;
- }
客戶端應(yīng)在apikey HTTP頭中顯示其API密鑰。如果此標(biāo)頭丟失或?yàn)榭?第20行)，我們發(fā)送401響應(yīng)以告知客戶端需要進(jìn)行身份驗(yàn)證。第23行處理API鍵與地圖塊中的任何鍵都不匹配的情況 - 在這種情況下，api_keys.conf第2行的默認(rèn)參數(shù)將$ api_client_name設(shè)置為空字符串 - 我們發(fā)送403響應(yīng)告訴身份驗(yàn)證失敗的客戶端。
有了這個(gè)配置，Warehouse API現(xiàn)在可以實(shí)現(xiàn)API密鑰身份驗(yàn)證。
- $ curl https://api.example.com/api/warehouse/pricing/item001
- {"status":401,"message":"Unauthorized"}
- $ curl -H "apikey: thisIsInvalid" https://api.example.com/api/warehouse/pricing/item001
- {"status":403,"message":"Forbidden"}
- $ curl -H "apikey: 7B5zIqmRGXmrJTFmKa99vcit" https://api.example.com/api/warehouse/pricing/item001
- {"sku":"item001","price":179.99}
JWT身份驗(yàn)證
JSON Web令牌(JWT)越來(lái)越多地用于API身份驗(yàn)證。原生JWT支持是NGINX Plus獨(dú)有的，可以在我們的博客上驗(yàn)證JWT，如使用JWT和NGINX Plus驗(yàn)證API客戶端中所述。
