다음을 통해 공유

자체 호스팅 게이트웨이 마이그레이션 가이드

  • 아티클

적용 대상: 개발자 | 프리미엄

이 문서에서는 기존 자체 호스팅 게이트웨이 배포를 자체 호스팅 게이트웨이 v2로 마이그레이션하는 방법을 설명합니다.

Important

Azure API Management 자체 호스팅 게이트웨이 버전 0 및 버전 1 컨테이너 이미지에 대한 지원은 해당 구성 API v1과 함께 2023년 10월 1일에 종료됩니다. 사용 중단 설명서에서 자세히 알아보기

새로운 기능

고객이 자체 호스팅 게이트웨이를 더 쉽게 배포할 수 있도록 하기 위해 API 검사기 또는 할당량을 사용하지 않는 한 Azure Storage 대한 종속성을 제거하는 새 구성 API를 도입했습니다.

새로운 구성 API를 통해 고객은 기존 인프라에서 자체 호스팅 게이트웨이를 보다 쉽게 채택, 배포 및 운영할 수 있습니다.

고객이 게이트웨이를 사용해 보고 프로덕션 환경에 배포하는 가장 좋은 방법을 선택할 수 있도록 새로운 컨테이너 이미지 태그를 도입했습니다.

고객이 프로덕션에서 게이트웨이를 실행할 수 있도록 프로덕션 지침을 크기 조정하여 게이트웨이를 자동 크기 조정하고 Kubernetes 클러스터에서 고가용성을 위해 배포하는 방법을 다룹니다.

게이트웨이 연결, 새로운 인프라 요구 사항 및 연결이 끊어지면 어떻게 되는지 이 문서에서 자세히 알아봅니다.

필수 조건

자체 호스팅 게이트웨이 v2로 마이그레이션하기 전에 인프라가 요구 사항을 충족하는지 확인해야 합니다.

자체 호스팅 게이트웨이 v2로 마이그레이션

자체 호스팅 게이트웨이 v2에서 마이그레이션하려면 몇 가지 작은 단계를 수행해야 합니다.

  1. 새 컨테이너 이미지 사용
  2. 새 구성 API 사용
  3. 최소한의 보안 요구 사항 충족

컨테이너 이미지

2.0.0 이상을 사용하도록 배포 스크립트의 이미지 태그를 변경합니다.

또는 다른 컨테이너 이미지 태그 중 하나를 선택합니다.

사용 가능한 태그의 전체 목록은 여기에서 찾거나 Docker Hub에서 찾을 수 있습니다.

새 구성 API 사용

자체 호스팅 게이트웨이 v2로 마이그레이션하려면 고객이 새로운 구성 API v2를 사용해야 합니다.

현재 Azure API Management는 자체 호스팅 게이트웨이에 대해 다음 구성 API를 제공합니다.

구성 서비스 URL 지원됨 요구 사항
v2 {name}.configuration.azure-api.net 예 링크
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview 아니요 링크

고객은 새 URL을 사용하고 인프라 요구 사항을 충족하도록 배포 스크립트를 변경하여 새 구성 API v2를 사용해야 합니다.

Important

  • DNS 호스트 이름은 IP 주소로 확인할 수 있어야 하며 해당 IP 주소에 연결할 수 있어야 합니다. 프라이빗 DNS, 내부 VNET 또는 기타 인프라 요구 사항을 사용하는 경우 추가 구성이 필요할 수 있습니다.

보안

사용 가능한 TLS 암호화 도구 모음

출시 당시 자체 호스팅 게이트웨이 v2.0은 v1.x에서 사용하던 암호화 도구 모음의 하위 집합만 사용했습니다. v2.0.4부터 v1.x에서 지원하는 모든 암호화 도구 모음을 다시 가져왔습니다.

이 문서에서 사용된 암호화 도구 모음에 대해 자세히 알아보거나 v2.1.1을 사용하여 사용할 암호화 도구 모음을 제어할 수 있습니다.

최소한의 보안 요구 사항 충족

시작하는 동안 자체 호스팅 게이트웨이는 사용할 CA 인증서를 준비합니다. 이를 위해서는 게이트웨이 컨테이너가 사용자 ID 1001 이상으로 실행되어야 하며 읽기 전용 파일 시스템을 사용할 수 없습니다.

Kubernetes에서 컨테이너에 대한 보안 컨텍스트를 구성할 때 최소한 다음이 필요합니다.

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

그러나 2.0.3부터 자체 호스팅 게이트웨이는 Kubernetes에서 루트가 아닌 사용자로 실행할 수 있으므로 고객이 게이트웨이를 더 안전하게 실행할 수 있습니다.

다음은 자체 호스팅 게이트웨이에 대한 보안 컨텍스트의 예입니다.

securityContext:
  allowPrivilegeEscalation: false
  runAsNonRoot: true
  runAsUser: 1001       # This is a built-in user, but you can use any user ie 1000 as well
  runAsGroup: 2000      # This is just an example
  privileged: false
  capabilities:
    drop:
    - all

Warning

읽기 전용 파일 시스템(readOnlyRootFilesystem: true)을 사용하여 자체 호스팅 게이트웨이를 실행하는 것은 지원되지 않습니다.

Azure Advisor를 사용하여 영향 평가

마이그레이션을 더 쉽게 하기 위해 새로운 Azure Advisor 권장 사항이 도입되었습니다.

  • 자체 호스팅 게이트웨이 v2 권장 사항 사용 - 자체 호스팅 게이트웨이 v0.x 또는 v1.x의 사용이 식별된 Azure API Management 인스턴스를 식별합니다.
  • 자체 호스팅 게이트웨이 권장 사항에 Configuration API v2 사용 - 자체 호스팅 게이트웨이에 대한 Configuration API v1 사용이 식별된 Azure API Management 인스턴스를 식별합니다.

고객은 Azure Advisor의 "모든 권장 사항" 개요를 사용하여 마이그레이션이 필요한지 확인하는 것이 좋습니다. 필터링 옵션을 사용하여 위의 권장 사항 중 하나가 있는지 확인합니다.

Azure Resource Graph를 사용하여 Azure API Management 인스턴스 식별

이 Azure Resource Graph 쿼리는 영향을 받은 Azure API Management 인스턴스 목록을 제공합니다.

AdvisorResources
| where type == 'microsoft.advisor/recommendations'
| where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence'
| extend
    recommendationTitle = properties.shortDescription.solution
| where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways'
| extend
    instanceName = properties.impactedValue,
    recommendationImpact = properties.impact,
    recommendationMetadata = properties.extendedProperties,
    lastUpdated = properties.lastUpdated
| project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, recommendationMetadata, lastUpdated

az graph query -q "AdvisorResources | where type == 'microsoft.advisor/recommendations' | where properties.impactedField == 'Microsoft.ApiManagement/service' and properties.category == 'OperationalExcellence' | extend recommendationTitle = properties.shortDescription.solution | where recommendationTitle == 'Use self-hosted gateway v2' or recommendationTitle == 'Use Configuration API v2 for self-hosted gateways' | extend instanceName = properties.impactedValue, recommendationImpact = properties.impact, recommendationMetadata = properties.extendedProperties, lastUpdated = properties.lastUpdated | project tenantId, subscriptionId, resourceGroup, instanceName, recommendationTitle, recommendationImpact, lastUpdated"

알려진 제한 사항

자체 호스팅 게이트웨이 v2에 대해 알려진 제한 사항 목록은 다음과 같습니다.

  • 구성 API v2는 사용자 지정 도메인 이름을 지원하지 않습니다.

다음 단계