이 글은 NGINX Open Source와 NGINX Plus를 API 게이트웨이로 배포하는 방법을 다루는 블로그 시리즈의 첫 번째 글입니다:
- 이 게시물에서는 여러 사용 사례에 대한 자세한 구성 지침을 제공합니다. 2018년에 처음 게시되었으며, 최신 API 구성 모범 사례를 반영하도록 업데이트되었습니다. 재작성 규칙 대신 중첩된
location블록을 사용하여 요청을 라우팅합니다. - 2부에서는 이러한 사용 사례를 확장하고, 프로덕션 환경의 백엔드 API 서비스를 보호하고 보안을 강화하기 위해 적용할 수 있는 다양한 보호 조치를 살펴봅니다.
- 3부에서는 NGINX Open Source와 NGINX Plus를 gRPC 서비스용 API 게이트웨이로 배포하는 방법을 설명합니다.
참고: 별도로 명시된 경우를 제외하고, 이 게시물의 모든 정보는 NGINX Open Source와 NGINX Plus 모두에 적용됩니다. 가독성을 위해 이 블로그의 나머지 부분에서는 두 제품을 간단히 “NGINX”로 지칭합니다.
현대적인 애플리케이션 아키텍처의 핵심은 HTTP API입니다. HTTP를 사용하면 애플리케이션을 빠르게 구축하고 쉽게 유지 관리할 수 있습니다. HTTP API는 단일 목적의 마이크로서비스부터 모든 기능을 아우르는 모놀리스까지 애플리케이션 규모에 관계없이 공통 인터페이스를 제공합니다. HTTP를 사용하면 초대규모 인터넷 서비스를 뒷받침하는 웹 애플리케이션 전송 기술의 발전을 활용하여 안정적인 고성능 API 전송도 구현할 수 있습니다.
마이크로서비스 애플리케이션에서 API 게이트웨이가 중요한 이유를 알기 쉽게 설명한 F5 블로그 글 마이크로서비스 구축: API 게이트웨이 사용을 참조하세요.
NGINX는 고성능 경량 리버스 프록시 및 로드 밸런서 분야를 선도하며, API 트래픽 처리에 필요한 고급 HTTP 처리 기능을 갖추고 있습니다. 따라서 API 게이트웨이를 구축하는 데 이상적인 플랫폼입니다. 이 블로그 게시물에서는 일반적인 API 게이트웨이 사용 사례 몇 가지를 살펴보고, 효율적이고 확장 가능하며 유지 관리가 쉬운 방식으로 이러한 사례를 처리하도록 NGINX를 구성하는 방법을 설명합니다. 프로덕션 배포의 기반으로 활용할 수 있는 전체 구성도 소개합니다.
Warehouse API 소개
API 게이트웨이의 주된 기능은 백엔드의 구현 또는 배포 방식과 관계없이 여러 API에 단일한 일관된 진입점을 제공하는 것입니다. 모든 API가 마이크로서비스 애플리케이션인 것은 아닙니다. 이 API 게이트웨이는 기존 API, 모놀리스, 마이크로서비스로 부분 전환 중인 애플리케이션을 관리해야 합니다.
이 블로그 게시물에서는 재고 관리를 위한 가상의 API인 “Warehouse API”를 예로 들어 설명합니다. 샘플 구성 코드를 사용하여 다양한 사용 사례를 살펴봅니다. Warehouse API는 JSON 요청을 받아 JSON 응답을 생성하는 RESTful API입니다. 하지만 NGINX를 API 게이트웨이로 배포할 때 JSON 사용이 제약 조건이나 필수 요건인 것은 아닙니다. NGINX는 API 자체의 아키텍처 스타일이나 데이터 형식에 구애받지 않습니다.
Warehouse API는 개별 마이크로서비스의 집합으로 구현되며 단일 API로 공개됩니다. 재고 및 가격 리소스는 별도의 서비스로 구현되어 서로 다른 백엔드에 배포됩니다. 따라서 API의 경로 구조는 다음과 같습니다.
api
└── warehouse
├── inventory
└── pricing예를 들어, 현재 창고 재고를 조회하려면 클라이언트 애플리케이션이 HTTP GET 요청을 /api/warehouse/inventory로 전송합니다.

NGINX 구성 체계화
NGINX를 API 게이트웨이로 사용하면 API 게이트웨이 역할을 수행하는 동시에 기존 HTTP 트래픽을 위한 리버스 프록시, 로드 밸런서, 웹 서버로도 작동할 수 있다는 장점이 있습니다. NGINX가 이미 애플리케이션 제공 스택에 포함되어 있다면 일반적으로 별도의 API 게이트웨이를 배포할 필요가 없습니다. 다만 API 게이트웨이에 기대되는 기본 동작 중 일부는 브라우저 기반 트래픽 처리에 기대되는 동작과 다릅니다. 따라서 API 게이트웨이 구성을 브라우저 기반 트래픽을 위한 기존 구성이나 향후 구성과 분리합니다.
이러한 분리를 위해 다목적 NGINX 인스턴스를 지원하고 CI/CD 파이프라인을 통해 구성 배포를 손쉽게 자동화할 수 있는 구성 레이아웃을 만듭니다. 이에 따른 /etc/nginx 하위 디렉터리 구조는 다음과 같습니다.
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 게이트웨이 구성 디렉터리와 파일 이름에는 접두사로 api_가 붙습니다. 아래에서 자세히 설명하듯이, 각 파일과 디렉터리는 API 게이트웨이의 서로 다른 기능을 활성화합니다. warehouse_api.conf 파일은 아래에서 설명하는, Warehouse API를 다양한 방식으로 정의하는 구성 파일을 통칭하는 예시 파일입니다.
최상위 API 게이트웨이 정의
모든 NGINX 구성은 기본 구성 파일인 nginx.conf에서 시작합니다. API 게이트웨이 구성을 읽어오려면 include 지시문을 http 블록에 추가합니다. 이 블록은 nginx.conf에 있으며, 추가한 지시문은 게이트웨이 구성이 담긴 파일인 api_gateway.conf를 참조합니다(바로 아래 28행). 기본 nginx.conf 파일은 include 지시문을 사용하여 conf.d 하위 디렉터리에서 브라우저 기반 HTTP 구성을 불러옵니다(29행). 이 블로그 게시물에서는 가독성을 높이고 구성의 일부를 자동화할 수 있도록 include 지시문을 광범위하게 사용합니다.
코드 예제를 로드하는 중…
The api_gateway.conf 파일은 클라이언트에 NGINX를 API 게이트웨이로 제공하는 가상 서버를 정의합니다. 이 구성은 API 게이트웨이가 게시하는 모든 API를 단일 진입점인 https://api.example.com/(9행)에서 제공하며, 이 진입점은 12~17행의 구성에 따라 TLS로 보호됩니다. 이 구성은 HTTPS만 사용하며, 평문 HTTP 리스너는 없다는 점에 유의하세요. API 클라이언트는 올바른 진입점을 알고 기본적으로 HTTPS 연결을 사용한다고 가정합니다.
이 구성은 정적으로 유지하도록 설계되었습니다. 개별 API와 해당 백엔드 서비스의 세부 정보는 20행의 include 지시문이 참조하는 파일에 지정됩니다. 23~26행은 오류 처리를 다루며, 아래의 오류에 대응하기에서 설명합니다.
코드 예제를 로드하는 중…
단일 서비스 API 백엔드와 마이크로서비스 API 백엔드 비교
일부 API는 단일 백엔드에 구현될 수도 있지만, 일반적으로 복원력이나 부하 분산을 위해 둘 이상의 백엔드를 사용한다고 가정합니다. 마이크로서비스 API에서는 서비스별로 개별 백엔드를 정의하며, 이러한 백엔드가 함께 완전한 API로 작동합니다. 여기서 Warehouse API는 두 개의 별도 서비스로 배포되며, 각 서비스에는 여러 백엔드가 있습니다.
코드 예제를 로드하는 중…
API 게이트웨이가 게시하는 모든 API의 백엔드 API 서비스를 정의하는 파일은 api_backends.conf입니다. 여기서는 API 코드가 배포된 위치를 나타내기 위해 각 upstream 블록에 여러 IP 주소-포트 쌍을 사용하지만, 호스트 이름을 사용할 수도 있습니다. NGINX Plus 구독자는 동적 DNS 부하 분산을 활용하여 새 백엔드가 런타임 구성에 자동으로 추가되도록 할 수도 있습니다.
Warehouse API 정의
Warehouse API는 다음 예와 같이 중첩 구성의 여러 location 블록으로 정의합니다. 외부 location 블록(/api/warehouse)은 기본 경로를 지정하며, 그 안에 중첩된 location은 백엔드 API 서비스로 라우팅되는 유효한 URI를 지정합니다. 외부 블록을 사용하면 전체 API에 적용되는 공통 정책을 정의할 수 있습니다(이 예에서는 6행의 로깅 구성).
코드 예제를 로드하는 중…
NGINX는 요청 URI를 구성의 특정 섹션과 매칭하는 매우 효율적이고 유연한 시스템을 갖추고 있습니다. location 지시어의 순서는 중요하지 않으며, 가장 구체적으로 일치하는 항목이 선택됩니다. 여기서 10행과 14행의 중첩된 location은 외부 location 블록보다 더 구체적인 두 URI를 정의합니다. 각 중첩 블록의 proxy_pass 지시어는 요청을 적절한 업스트림 그룹으로 라우팅합니다. 특정 URI에 더 구체적인 정책을 적용해야 하는 경우가 아니면 정책 구성은 외부 location에서 상속됩니다.
중첩된 location 중 어느 것과도 일치하지 않는 URI는 외부 location에서 처리합니다. 외부 location에는 모든 유효하지 않은 URI에 대해 404 (Not Found) 응답을 반환하는 포괄 지시문(18행)이 포함되어 있습니다.
API 정의 방식 선택: 포괄적 정의와 정밀한 정의
API를 정의하는 방식에는 광범위한 정의와 정밀한 정의, 두 가지가 있습니다. 각 API에 가장 적합한 방식은 해당 API의 보안 요구 사항과 백엔드 서비스에서 유효하지 않은 URI를 처리하는 것이 바람직한지에 따라 달라집니다.
위의 warehouse_api_simple.conf에서는 Warehouse API에 포괄적인 정의 방식을 사용합니다. 10행과 14행에 URI 접두사를 정의하여 해당 접두사 중 하나로 시작하는 URI를 적절한 백엔드 서비스로 프록시합니다. 이처럼 접두사 기반으로 포괄적인 location 매칭을 수행하면 다음 URI에 대한 API 요청은 모두 유효합니다:
/api/warehouse/inventory
/api/warehouse/inventory/
/api/warehouse/inventory/foo
/api/warehouse/inventoryfoo
/api/warehouse/inventoryfoo/bar/
각 요청을 올바른 백엔드 서비스로 프록시하는 것만 고려한다면, 포괄적인 방식이 가장 빠른 처리 속도와 가장 간결한 구성을 제공합니다. 반면, 더 정밀한 방식은 사용 가능한 각 API 리소스의 URI 경로를 명시적으로 정의하여 API 게이트웨이가 API의 전체 URI 공간을 파악할 수 있게 합니다. 이러한 정밀한 방식을 적용한 다음 Warehouse API의 URI 라우팅 구성은 정확한 일치(=)와 정규 표현식(~)을 조합하여 유효한 URI를 빠짐없이 정의합니다.
코드 예제를 로드하는 중…
이 구성은 더 길지만 백엔드 서비스가 구현하는 리소스를 더 정확하게 기술합니다. 정규식 매칭에 약간의 오버헤드가 추가되지만, 잘못된 형식의 클라이언트 요청으로부터 백엔드 서비스를 보호한다는 이점이 있습니다. 이 구성을 적용하면 NGINX는 일부 URI를 허용하고 나머지는 유효하지 않은 것으로 판단하여 거부합니다.
유효한 URI 유효하지 않은 URI
/api/warehouse/inventory
/api/warehouse/inventory/
/api/warehouse/inventory/shelf/foo
/api/warehouse/inventoryfoo
/api/warehouse/inventory/shelf/foo/box/bar
/api/warehouse/inventory/shelf/api/warehouse/inventory/shelf/-/box/-
/api/warehouse/inventory/shelf/foo/bar
/api/warehouse/pricing/baz
/api/warehouse/pricing
/api/warehouse/pricing/baz/pub
정확한 API 정의를 사용하면 기존 API 문서 형식을 기반으로 API 게이트웨이를 구성할 수 있습니다. OpenAPI Specification(이전 명칭: Swagger)을 기반으로 NGINX API 정의를 자동화할 수 있습니다. 이를 위한 샘플 스크립트는 이 블로그 게시물의 Gist 모음에서 제공됩니다.
호환성을 깨뜨리는 변경 사항에 대응하기 위한 클라이언트 요청 재작성
API가 발전함에 따라 엄격한 하위 호환성을 유지할 수 없고 클라이언트 업데이트가 필요한 변경을 해야 할 때가 있습니다. API 리소스의 이름이나 위치가 바뀌는 경우가 그 예입니다. 웹 브라우저와 달리 API 게이트웨이는 새 위치를 알리는 리디렉션(코드 301 (Moved Permanently))을 클라이언트에 보낼 수 없습니다. 다행히 API 클라이언트를 수정하기 어려운 경우에는 클라이언트 요청을 실시간으로 재작성할 수 있습니다.
다음 예제에서는 앞서 살펴본 warehouse_api_simple.conf와 전반적으로 동일한 접근 방식을 사용하지만, 이 구성은 가격 서비스가 재고 서비스의 일부로 구현되었던 이전 버전의 Warehouse API를 대체합니다. 3행의 rewrite 지시문은 기존 가격 리소스에 대한 요청을 새 가격 서비스에 대한 요청으로 변환합니다.
코드 예제를 로드하는 중…
오류 대응
HTTP API와 브라우저 기반 트래픽의 주요 차이점 중 하나는 클라이언트에 오류를 전달하는 방식입니다. NGINX를 API 게이트웨이로 배포할 때는 API 클라이언트에 가장 적합한 방식으로 오류를 반환하도록 구성합니다.
최상위 API 게이트웨이 구성에는 오류 응답 처리 방식을 정의하는 섹션이 포함되어 있습니다.
코드 예제를 로드하는 중…
The error_page 지시문은 23행에 있으며, 요청이 어떤 API 정의와도 일치하지 않으면 NGINX가 400 (Bad Request) 오류를 반환하도록 지정합니다. 이 오류는 기본 오류인 404 (Not Found) 오류를 대신합니다. 이 동작은 선택 사항으로, API 클라이언트가 API 문서에 포함된 유효한 URI로만 요청하도록 요구하며, 권한이 없는 클라이언트가 API 게이트웨이를 통해 게시된 API의 URI 구조를 알아내지 못하도록 합니다.
24행은 백엔드 서비스 자체에서 발생한 오류를 가리킵니다. 처리되지 않은 예외에는 클라이언트에 전송해서는 안 되는 스택 추적이나 기타 민감한 데이터가 포함될 수 있습니다. 이 구성은 클라이언트에 표준화된 오류 응답을 전송하여 보호 수준을 한층 높입니다.
표준화된 오류 응답의 전체 목록은 25행의 include 지시문이 참조하는 별도의 구성 파일에 정의되어 있으며, 이 파일의 처음 몇 행은 아래에 나와 있습니다. JSON 이외의 오류 형식을 사용하려면 이 파일을 수정하고, default_type 값을 api_gateway.conf의 26행에서 해당 형식에 맞게 변경하면 됩니다. 또한 각 API의 정책 섹션에 별도의 include 지시문을 추가하여 전역 응답을 재정의하는 오류 응답이 담긴 다른 파일을 참조할 수도 있습니다.
코드 예제를 로드하는 중…
이 구성을 적용하면 유효하지 않은 URI에 대한 클라이언트 요청에 다음 응답이 반환됩니다. [terminal]$ curl -i https://api.example.com/foo HTTP/1.1 400 Bad Request Server: nginx/1.19.5 Content-Type: application/json Content-Length: 39 Connection: keep-alive {"status":400,"message":"Bad request"}[/terminal]인증 구현
일반적으로 API를 공개할 때는 API를 보호하기 위해 어떤 형태로든 인증을 적용합니다. NGINX는 API를 보호하고 API 클라이언트를 인증하는 여러 방법을 제공합니다. 일반 HTTP 요청에도 적용할 수 있는 방법에 대한 자세한 내용은 IP 주소 기반 액세스 제어 목록(ACL), 디지털 인증서 인증, HTTP 기본 인증 관련 문서를 참조하세요. 여기서는 API에 특화된 인증 방법을 중점적으로 살펴봅니다.
API 키 인증
API 키는 클라이언트와 API 게이트웨이가 공유하는 비밀 정보입니다. API 키는 기본적으로 장기 자격 증명으로 API 클라이언트에 발급되는 길고 복잡한 비밀번호입니다. API 키는 간단하게 생성할 수 있습니다. 이 예제처럼 난수를 인코딩하기만 하면 됩니다.
$ openssl rand -base64 187B5zIqmRGXmrJTFmKa99vcit최상위 API 게이트웨이 구성 파일인 api_gateway.conf의 2행에는 api_keys.conf 파일을 포함합니다. 이 파일에는 클라이언트 이름이나 기타 설명으로 식별되는 각 API 클라이언트의 API 키가 들어 있습니다. 파일 내용은 다음과 같습니다:
코드 예제를 로드하는 중…
API 키는 map 블록 내에 정의됩니다. map 지시문은 두 개의 매개변수를 사용합니다. 첫 번째 매개변수는 API 키를 찾을 위치를 지정합니다. 이 예에서는 클라이언트 요청의 apikey HTTP 헤더이며, 해당 값은 $http_apikey 변수에 저장됩니다. 두 번째 매개변수는 새 변수($api_client_name)를 생성하고, 첫 번째 매개변수가 키와 일치하는 줄의 두 번째 매개변수 값으로 설정합니다.
예를 들어 클라이언트가 API 키 7B5zIqmRGXmrJTFmKa99vcit를 제시하면 $api_client_name 변수는 client_one으로 설정됩니다. 이 변수는 인증된 클라이언트를 확인하는 데 사용할 수 있으며, 더 상세한 감사를 위해 로그 항목에 포함할 수도 있습니다. map 블록은 형식이 단순하며, 기존 자격 증명 저장소에서 api_keys.conf 파일을 생성하는 자동화 워크플로에 쉽게 통합할 수 있습니다.
여기서는 “광범위한” 구성(warehouse_api_simple.conf)의 정책 섹션에 인증 결정을 지정된 위치에 위임하는 auth_request 지시문을 추가하여 API 키 인증을 활성화합니다.
코드 예제를 로드하는 중…
With the auth_request 지시문(7행)을 사용하면 예를 들어 OAuth 2.0 토큰 인트로스펙션과 같은 외부 인증 서버에서 인증을 처리하도록 할 수 있습니다. 이 예제에서는 그 대신 API 키를 검증하는 로직을 최상위 API 게이트웨이 구성 파일에 다음과 같은 location 블록으로 추가합니다. 이 블록의 이름은 /_validate_apikey입니다.
코드 예제를 로드하는 중…
30행의 internal 지시문은 외부 클라이언트가 이 위치에 직접 접근할 수 없음을 의미합니다(auth_request로만 접근 가능). 클라이언트는 apikey HTTP 헤더에 API 키를 제공해야 합니다. 이 헤더가 없거나 비어 있으면(32행) 401 (Unauthorized) 응답을 보내 클라이언트에 인증이 필요함을 알립니다. 35행에서는 API 키가 map 블록의 어떤 키와도 일치하지 않는 경우를 처리합니다. 이 경우 default 매개변수(api_keys.conf의 2행)가 $api_client_name을 빈 문자열로 설정하며, 403 (Forbidden) 응답을 보내 클라이언트에 인증 실패를 알립니다. 두 조건 중 어느 것에도 해당하지 않으면 API 키가 유효하며, 이 위치는 204 (No Content) 응답을 반환합니다.
이 구성을 적용하면 Warehouse API에서 API 키 인증을 수행합니다.
$ 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 인증
JSON 웹 토큰(JWT)은 API 인증에 점점 더 많이 사용되고 있습니다. JWT 기본 지원은 NGINX Plus에서만 제공되며, 블로그의 JWT와 NGINX Plus를 사용한 API 클라이언트 인증에 설명된 대로 JWT를 검증할 수 있습니다. 구현 예는 2부의 특정 메서드에 대한 액세스 제어를 참조하세요.
요약
시리즈의 첫 번째 블로그 글에서는 NGINX Open Source와 NGINX Plus를 API 게이트웨이로 배포하는 완전한 솔루션을 자세히 설명합니다. 이 글에서 다루는 전체 파일은 GitHub Gist 저장소에서 확인하고 다운로드할 수 있습니다.
이 시리즈의 다른 게시물도 확인해 보세요:
- 2부에서는 악의적이거나 비정상적으로 동작하는 클라이언트로부터 백엔드 서비스를 보호하는 고급 활용 사례를 살펴봅니다.
- 3부에서는 gRPC 서비스를 위한 API 게이트웨이로 NGINX를 배포하는 방법을 설명합니다.
NGINX Plus를 체험하려면 30일 무료 체험을 오늘 시작하거나 문의하여 활용 사례를 상담하세요.
작성자 소개

관련 블로그 게시물
시청하기: KubeCon North America 2023에서의 NGINX Gateway Fabric
이 영상에서는 KubeCon의 NGINX 부스를 찾아가, 저희가 공개한 Kubernetes Gateway API 구현을 살펴봅니다.
F5 NGINX로 대규모 WAF 플릿을 확인하고 관리하는 2가지 방법
앱 보안을 강화하는 두 가지 방법을 소개합니다. NGINX Management Suite를 통해 WAF 운영에 대한 가시성을 높이고, NGINX App Protect WAF를 활용해 코드형 보안을 구현하는 것입니다.
인그레스 컨트롤러 선택 가이드, 4부: NGINX 인그레스 컨트롤러 옵션
개발 주체, 개발 철학, 프로덕션 환경 적합성, 보안 및 지원을 기준으로 어떤 NGINX Ingress 컨트롤러가 가장 적합한지 알아보세요.
진화하는 공격 환경에 NGINX App Protect Denial of Service가 적응하는 방법
NGINX App Protect Denial of Service(DoS)가 계층 7 DoS 공격을 방어하기 위해 완화 방법을 실시간으로 조정하는 방식을 설명합니다. 정상적인 사용자 행동과 서버 상태에 대한 모델을 생성하여 공격을 나타내는 이상 징후를 감지하고 맞춤형 완화 시그니처를 적용할 수 있습니다.
NGINX Instance Manager를 활용한 대규모 구성 업데이트 및 인증서 관리
NGINX Instance Manager 버전 1.0에는 두 가지 새로운 기능이 도입되었습니다. NGINX 인스턴스에 태그와 사용자 역할을 지정하면 전체 그룹에 구성을 한 번에 적용할 수 있습니다. 인증서 검사는 만료 예정인 인증서를 감지하여 서비스 중단을 방지할 수 있도록 인증서를 교체할 수 있게 해줍니다.
Netflix가 자사 CDN의 핵심으로 NGINX를 선택한 이유
Netflix가 글로벌 콘텐츠 전송 네트워크인 Open Connect의 스트리밍 미디어 기술로 NGINX를 선택한 이유를 NGINX 개발자 Gleb Smirnoff에게서 알아보세요.