Spring Cloud Gateway 사용

참고 항목

Azure Spring Apps는 Azure Spring Cloud 서비스의 새 이름입니다. 서비스에 새 이름이 지정되었지만, 자산을 업데이트하는 동안 스크린샷, 비디오, 다이어그램과 같은 일부 위치에서는 당분간 이전 이름이 표시됩니다.

이 문서의 적용 대상:❌ 기본/표준 ✔️ 엔터프라이즈

이 문서에서는 Azure Spring Apps Enterprise 계획과 함께 VMware Spring Cloud Gateway를 사용하여 요청을 애플리케이션으로 라우팅하는 방법을 보여 줍니다.

VMware Spring Cloud Gateway는 오픈 소스 Spring Cloud Gateway 프로젝트를 기반으로 하는 상업용 VMware Tanzu 구성 요소입니다. Spring Cloud Gateway는 SSO(Single Sign-On), 액세스 제어, 속도 제한, 복원력, 보안 등과 같은 API 개발 팀의 공통 관심 사항을 처리합니다. 최신 클라우드 네이티브 패턴과 API 개발을 위해 선택하는 프로그래밍 언어를 사용하여 API 제공을 가속화할 수 있습니다.

Spring Cloud Gateway에는 다음 기능이 포함되어 있습니다.

• 동적 라우팅 구성. 다시 컴파일하지 않고 적용 및 변경할 수 있는 개별 애플리케이션과 별개입니다.
• 권한 있는 JWT(JSON Web Token) 클레임을 애플리케이션 서비스로 전송하기 위한 상업용 API 경로 필터
• 클라이언트 인증서 권한 부여.
• 속도 제한 방법.
• 회로 차단기 구성.
• HTTP 기본 인증 자격 증명을 통해 애플리케이션 서비스에 대한 액세스 지원.

VMware Tanzu용 API 포털과 통합하기 위해 VMware Spring Cloud Gateway는 경로 구성이 추가 또는 변경된 후 OpenAPI 버전 3 설명서를 자동으로 생성합니다.

필수 조건

• Spring Cloud Gateway가 사용 설정된 이미 프로비전된 Azure Spring Apps 엔터프라이즈 계획 서비스 인스턴스. 자세한 내용은 빠른 시작: 엔터프라이즈 계획을 사용하여 Azure Spring Apps에 앱 빌드 및 배포를 참조하세요.
• Azure CLI 버전 2.0.67 이상 az extension add --name spring 명령을 사용하여 Azure Spring Apps 확장을 설치합니다.

경로 구성

이 섹션에서는 Spring Cloud Gateway를 사용하는 앱의 API 경로를 추가, 업데이트 및 관리하는 방법을 설명합니다.

경로 구성 정의에는 다음과 같은 부분이 포함됩니다.

• OpenAPI URI: 이 URI는 OpenAPI 사양을 참조합니다. https://petstore3.swagger.io/api/v3/openapi.json과 같은 공용 URI 엔드포인트 또는 http://<app-name>/{relative-path-to-OpenAPI-spec}와 같은 생성된 URI를 사용할 수 있습니다. 여기서 <app-name>는 API 정의를 포함하는 Azure Spring Apps의 애플리케이션 이름입니다. OpenAPI 2.0 및 OpenAPI 3.0 사양이 모두 지원됩니다. 사용하도록 설정하면 API 포털에 사양이 표시됩니다.
• routes: 트래픽을 앱으로 보내고 필터를 적용하는 라우팅 규칙 목록입니다.
• Spring Cloud Gateway가 트래픽을 라우팅하는 애플리케이션의 백 엔드 프로토콜입니다. 프로토콜의 지원되는 값은 HTTP 또는 HTTPS이며 기본값은 HTTP입니다. Spring Cloud Gateway에서 HTTPS 지원 애플리케이션으로의 트래픽을 보호하려면 경로 구성에서 프로토콜을 HTTPS로 설정해야 합니다.
• 앱 수준 경로: 경로 구성의 전체 또는 대부분의 경로에서 반복을 방지하기 위해 앱 수준에서 구성할 수 있는 세 가지 경로 속성이 있습니다. 구체적인 라우팅 규칙은 동일한 속성의 앱 수준 라우팅 규칙을 재정의합니다. 앱 수준에서 predicates, filters, ssoEnabled 속성을 정의할 수 있습니다. OpenAPI URI 기능을 사용하여 경로를 정의하는 경우 지원할 유일한 앱 수준 라우팅 속성은 filters입니다.

다음 명령을 사용하여 경로 구성을 만듭니다. --app-name 값은 요청이 라우팅될 Azure Spring Apps에서 호스트되는 앱의 이름이어야 합니다.

az spring gateway route-config create \
    --name <route-config-name> \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --app-name <app-name> \
    --routes-file <routes-file.json>

다음 예제에서는 create 명령의 --routes-file 매개 변수에 전달되는 JSON 파일을 보여 줍니다.

{
   "predicates": [
      "<app-level-predicate-of-route>",
   ],
   "ssoEnabled": false,
   "filters": [
      "<app-level-filter-of-route>",
   ],
   "openApi": {
      "uri": "<OpenAPI-URI>"
   },
   "protocol": "<protocol-of-routed-app>",
   "routes": [
      {
         "title": "<title-of-route>",
         "description": "<description-of-route>",
         "predicates": [
            "<predicate-of-route>",
         ],
         "ssoEnabled": true,
         "filters": [
            "<filter-of-route>",
         ],
         "tags": [
            "<tag-of-route>"
         ],
         "order": 0
      }
   ]
}

다음 표에는 경로 정의가 나와 있습니다. 모든 속성은 선택 사항입니다.

속성	설명
title	생성된 OpenAPI 설명서의 메서드에 적용되는 제목
description	생성된 OpenAPI 설명서의 메서드에 적용되는 설명
uri	요청이 라우팅하는 앱의 이름을 재정의하는 전체 URI입니다.
ssoEnabled	SSO 유효성 검사를 사용하도록 설정되어 있는지 나타내는 값 Single Sign-On 구성을 참조하세요.
tokenRelay	현재 인증된 사용자의 ID 토큰을 애플리케이션에 전달합니다.
조건자	조건자 목록입니다. 사용 가능한 조건자를 참조하세요.
필터	필터 목록입니다. 사용 가능한 필터를 참조하세요.
order	경로 처리 순서 Spring Cloud Gateway에서와 같이 더 낮은 순서가 더 높은 우선 순위로 처리됩니다.
tags	생성된 OpenAPI 설명서의 메서드에 적용되는 분류 태그입니다.

참고 항목

보안 또는 호환성 때문에 일부 필터/조건자는 Azure Spring Apps에서 지원되지 않습니다. 지원되지 않는 항목은 다음과 같습니다.

• BasicAuth
• JWTKey

Spring Cloud Gateway의 경로 사용

Spring Cloud Gateway를 사용하여 샘플 애플리케이션을 만들려면 다음 단계를 수행합니다.

1. 다음 명령을 사용하여 Azure Spring Apps에서 test-app이라는 테스트 애플리케이션을 만듭니다.

   az spring app create \
       name test-app \
       resource-group <resource-group-name> \
       service <Azure-Spring-Apps-instance-name>
   

2. 게이트웨이에 퍼블릭 엔드포인트를 할당하여 액세스합니다.

   Spring Cloud Gateway에 제공된 실행 상태 및 리소스를 보려면 Azure Portal에서 Azure Spring Apps 인스턴스를 열고 Spring Cloud Gateway 섹션을 선택한 다음, 개요를 선택합니다.

   공용 엔드포인트를 할당하려면엔드포인트 할당 옆에 있는 예를 선택합니다. URL이 몇 분 안에 나타납니다. 나중에 사용할 수 있도록 URL을 저장합니다.

   

   Azure CLI를 사용하여 엔드포인트를 할당할 수도 있습니다. 다음 명령을 사용하여 엔드포인트를 할당합니다.

   az spring gateway update \
       --resource-group <resource-group-name> \
       --service <Azure-Spring-Apps-instance-name> \
       --assign-endpoint true
   

3. Spring Cloud Gateway를 통해 테스트 앱의 상태 검사 엔드포인트에 액세스하는 규칙을 만듭니다.

   test-api.json 파일에 다음 콘텐츠를 저장합니다. 이 구성에는 10초마다 20개의 요청을 허용하는 RateLimit 필터와 요청 엔드포인트가 표준 Spring Boot 상태 검사 엔드포인트에 도달할 수 있도록 하는 RewritePath 필터가 포함됩니다.

   {
     "protocol": "HTTP",
     "routes": [
       {
         "title": "Test API",
         "description": "Retrieve a health check from our application",
         "predicates": [
           "Path=/test/api/healthcheck",
           "Method=GET"
         ],
         "filters": [
           "RateLimit=20,10s",
           "RewritePath=/api/healthcheck,/actuator/health"
         ],
         "tags": [
           "test"
         ]
       }
     ]
   }
   

   그런 다음, 다음 명령을 사용하여 test-app 앱에 규칙을 적용합니다.

   az spring gateway route-config create \
       --name test-api-routes \
       --resource-group <resource-group-name> \
       --service <Azure-Spring-Apps-instance-name> \
       --app-name test-app \
       --routes-file test-api.json
   

   다음 스크린샷과 같이 포털에서 경로를 볼 수도 있습니다.

   

4. 다음 명령을 사용하여 게이트웨이 엔드포인트를 통해 test health check API에 액세스합니다.

   curl https://<endpoint-url>/test/api/healthcheck
   

5. 다음 명령을 사용하여 라우팅 규칙을 쿼리합니다.

   az spring gateway route-config show \
       --name test-api-routes \
       --query '{appResourceId:properties.appResourceId, routes:properties.routes}'
   
   az spring gateway route-config list \
       --query '[].{name:name, appResourceId:properties.appResourceId, routes:properties.routes}'
   

필터 사용

오픈 소스 Spring Cloud Gateway 프로젝트에는 게이트웨이 경로에서 사용할 수 있는 많은 기본 제공 필터가 포함되어 있습니다. Spring Cloud Gateway는 OSS 프로젝트에 포함된 필터 외에도 많은 사용자 지정 필터를 제공합니다.

다음 예제에서는 경로에 AddRequestHeadersIfNotPresent 필터를 적용하는 방법을 보여줍니다.

[
  {
    "predicates": [
      "Path=/api/**",
      "Method=GET"
    ],
    "filters": [
      "AddRequestHeadersIfNotPresent=Content-Type:application/json,Connection:keep-alive"
    ]
  }
]

그런 다음, 다음 Azure CLI 명령을 사용하여 경로 정의를 적용합니다.

az spring gateway route-config create \
    --name <route-config-name> \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --app <app-name>
    --routes-file <json-file-with-routes>

사용 가능한 경로 필터에 대한 자세한 내용은 Azure Spring Apps Enterprise 계획에서 VMware Spring Cloud Gateway 경로 필터를 사용하는 방법을 참조하세요.

다음 단계

• Azure Spring Apps
• 빠른 시작: Enterprise 계획을 사용하여 Azure Spring Apps에 앱 빌드 및 배포