NGINX를 API 게이트웨이로 배포하기, 1부

Liam Crilly제품 관리 부문 수석 이사

NGINX Open Source 및 NGINX Plus를 API 게이트웨이로 배포하는 방법을 다루는 블로그 시리즈의 첫 번째 게시물입니다:

• 이 게시물에서는 여러 사용 사례에 대한 자세한 구성 지침을 제공합니다. 2018년에 처음 게시되었으며, 재작성 규칙 대신 중첩된 location 블록을 사용하여 요청을 라우팅하는 현재의 API 구성 모범 사례를 반영하도록 업데이트되었습니다.
• 2부에서는 이러한 사용 사례를 확장하고, 프로덕션 환경에서 백엔드 API 서비스를 보호하고 보안을 강화하기 위해 적용할 수 있는 다양한 안전장치를 살펴봅니다.
• 3부에서는 NGINX Open Source와 NGINX Plus를 gRPC 서비스용 API 게이트웨이로 배포하는 방법을 설명합니다.

참고: 별도로 명시된 경우를 제외하면 이 게시물의 모든 내용은 NGINX Open Source와 NGINX Plus 모두에 적용됩니다. 읽기 편하도록 이 블로그의 나머지 부분에서는 두 제품을 간단히 “NGINX”라고 지칭합니다.

현대적인 애플리케이션 아키텍처의 중심에는 HTTP API가 있습니다. HTTP를 사용하면 애플리케이션을 빠르게 구축하고 손쉽게 유지 관리할 수 있습니다. HTTP API는 단일 목적의 마이크로서비스부터 모든 기능을 아우르는 모놀리식 애플리케이션에 이르기까지 애플리케이션 규모와 관계없이 공통 인터페이스를 제공합니다. HTTP를 활용하면 하이퍼스케일 인터넷 서비스를 지원하는 웹 애플리케이션 전송 기술의 발전을 바탕으로 안정적인 고성능 API 전송도 구현할 수 있습니다.

마이크로서비스 애플리케이션에서 API 게이트웨이가 중요한 이유를 자세히 알아보려면 블로그의 마이크로서비스 구축: API 게이트웨이 사용하기 문서를 참조하세요.

고성능 경량 리버스 프록시 및 로드 밸런서 분야를 선도하는 NGINX는 API 트래픽 처리에 필요한 고급 HTTP 처리 기능을 갖추고 있습니다. 따라서 NGINX는 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 게이트웨이로 사용할 때의 장점 중 하나는 기존 HTTP 트래픽에 대한 리버스 프록시, 로드 밸런서 및 웹 서버 역할을 수행하는 동시에 API 게이트웨이 역할도 할 수 있다는 것입니다. 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 지시어를 nginx.conf의 http 블록에 추가하여 게이트웨이 구성이 포함된 파일인 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로 작동합니다. 여기서는 Warehouse API가 각각 여러 백엔드를 갖춘 두 개의 개별 서비스로 배포됩니다.

코드 예제를 로드하는 중…

API 게이트웨이에서 게시하는 모든 API의 백엔드 API 서비스는 모두 api_backends.conf에 정의됩니다. 여기서는 각 upstream 블록에 여러 IP 주소-포트 쌍을 사용하여 API 코드가 배포된 위치를 지정하지만, 호스트 이름을 사용할 수도 있습니다. 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 (찾을 수 없음) 응답을 반환하는 포괄 지시문(18행)이 포함되어 있습니다.

API의 포괄적 정의와 정밀한 정의 중 선택하기

API 정의에는 포괄적 정의와 정밀한 정의라는 두 가지 접근 방식이 있습니다. 각 API에 가장 적합한 접근 방식은 해당 API의 보안 요구 사항과 백엔드 서비스에서 유효하지 않은 URI를 처리하도록 하는 것이 바람직한지 여부에 따라 달라집니다.

위의 warehouse_api_simple.conf에서는 Warehouse API에 포괄적 접근 방식을 사용합니다. 즉, 10행과 14행에 URI 접두사를 정의하여 해당 접두사 중 하나로 시작하는 URI가 적절한 백엔드 서비스로 프록시되도록 합니다. 이처럼 접두사를 기반으로 위치를 포괄적으로 일치시키면 다음 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 명세(이전 명칭: Swagger)를 사용하여 NGINX API 정의를 자동화할 수 있습니다. 이를 위한 샘플 스크립트는 이 블로그 게시물의 Gist 모음에서 제공됩니다.

호환성을 깨뜨리는 변경 사항을 처리하기 위한 클라이언트 요청 재작성

API가 발전함에 따라 엄격한 하위 호환성을 깨고 클라이언트를 업데이트해야 하는 변경이 필요할 때가 있습니다. API 리소스의 이름이 바뀌거나 위치가 이동하는 경우가 그 예입니다. 웹 브라우저와 달리 API 게이트웨이는 새 위치를 알려 주는 리디렉션(코드 301 (영구 이동))을 클라이언트에 보낼 수 없습니다. 다행히 API 클라이언트를 수정하기 어려운 경우에는 클라이언트 요청을 즉석에서 재작성할 수 있습니다.

다음 예에서는 위의 warehouse_api_simple.conf과 동일한 전반적인 접근 방식을 사용하지만, 여기서는 가격 책정 서비스가 재고 서비스의 일부로 구현되어 있던 이전 버전의 Warehouse API를 이 구성으로 대체합니다. 3번째 줄의 rewrite 지시문은 이전 가격 책정 리소스에 대한 요청을 새로운 가격 책정 서비스에 대한 요청으로 변환합니다.

코드 예제를 로드하는 중…

오류에 응답하기

HTTP API와 브라우저 기반 트래픽의 주요 차이점 중 하나는 오류가 클라이언트에 전달되는 방식입니다. NGINX를 API 게이트웨이로 배포할 때는 API 클라이언트에 가장 적합한 방식으로 오류를 반환하도록 구성합니다.

최상위 API 게이트웨이 구성에는 오류 응답 처리 방법을 정의하는 섹션이 포함되어 있습니다.

코드 예제를 로드하는 중…

23번째 줄의 error_page 지시문은 요청이 어떤 API 정의와도 일치하지 않을 경우 NGINX가 기본 404 (Not Found) 오류 대신 400 (Bad Request) 오류를 반환하도록 지정합니다. 이 선택적 동작을 사용하면 API 클라이언트가 API 문서에 포함된 유효한 URI로만 요청을 보내야 하며, 권한이 없는 클라이언트가 API 게이트웨이를 통해 게시된 API의 URI 구조를 알아내는 것을 방지할 수 있습니다.

24번째 줄은 백엔드 서비스 자체에서 생성된 오류를 나타냅니다. 처리되지 않은 예외에는 클라이언트에 전송해서는 안 되는 스택 추적이나 기타 민감한 데이터가 포함될 수 있습니다. 이 구성은 표준화된 오류 응답을 클라이언트에 전송하여 보호 수준을 한층 더 강화합니다.

표준화된 오류 응답의 전체 목록은 25번째 줄의 include 지시문에서 참조하는 별도의 구성 파일에 정의되어 있으며, 해당 파일의 처음 몇 줄은 아래와 같습니다. JSON 이외의 오류 형식을 사용하려는 경우 이 파일을 수정하고, default_type의 26번째 줄에 있는 api_gateway.conf 값을 해당 형식에 맞게 변경할 수 있습니다. 또한 각 API의 정책 섹션에 별도의 include 지시문을 추가하여 전역 응답을 재정의하는 다른 오류 응답 파일을 참조할 수도 있습니다.

코드 예제를 로드하는 중…

인증 구현

API를 보호하기 위한 인증 수단 없이 게시하는 경우는 드뭅니다. NGINX는 API를 보호하고 API 클라이언트를 인증하기 위한 여러 가지 방법을 제공합니다. 일반 HTTP 요청에도 적용되는 방법에 대한 자세한 내용은 IP 주소 기반 액세스 제어 목록(ACL), 디지털 인증서 인증, HTTP 기본 인증 관련 문서를 참조하세요. 여기서는 API에 특화된 인증 방법을 중점적으로 살펴봅니다.

API 키 인증

API 키는 클라이언트와 API 게이트웨이만 알고 있는 공유 비밀 정보입니다. API 키는 본질적으로 API 클라이언트에 장기 자격 증명으로 발급되는 길고 복잡한 비밀번호입니다. API 키를 만드는 방법은 간단합니다. 이 예시처럼 난수를 인코딩하기만 하면 됩니다.

$ openssl rand -base64 187B5zIqmRGXmrJTFmKa99vcit

최상위 API 게이트웨이 구성 파일의 2번째 줄에서 api_gateway.conf라는 파일에 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 키 인증을 활성화합니다.

코드 예제를 로드하는 중…

예를 들어 auth_request 지시문(7행)을 사용하면 OAuth 2.0 토큰 검사와 같은 외부 인증 서버에서 인증을 처리하도록 할 수 있습니다. 이 예에서는 대신 API 키 검증 로직을 최상위 API 게이트웨이 구성 파일에 다음과 같은 location 블록 형태로 추가하며, 이 블록의 이름은 /_validate_apikey입니다.

코드 예제를 로드하는 중…

The internal 지시어는 30번째 줄에서 이 위치에 외부 클라이언트가 직접 액세스할 수 없으며 auth_request를 통해서만 액세스할 수 있음을 의미합니다. 클라이언트는 apikey HTTP 헤더에 API 키를 제공해야 합니다. 이 헤더가 없거나 비어 있으면(32번째 줄) 클라이언트에 인증이 필요함을 알리기 위해 401 (Unauthorized) 응답을 보냅니다. 35번째 줄에서는 API 키가 map 블록의 어떤 키와도 일치하지 않는 경우를 처리합니다. 이 경우 api_keys.conf의 2번째 줄에 있는 default 매개변수가 $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부에서는 NGINX를 gRPC 서비스용 API 게이트웨이로 배포하는 방법을 설명합니다.

NGINX Plus를 사용해 보려면 지금 30일 무료 체험을 시작하거나 문의하여 사용 사례에 대해 상담해 보세요.

작성자 소개

Liam Crilly제품 관리 부문 수석 이사

Liam Crilly의 다른 블로그 게시물