stv1 플랫폼에서 호스트되는 VNet 삽입 API Management 인스턴스를 stv2로 마이그레이션

아티클
11/04/2024

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

이 문서에서는 인스턴스가 외부 또는 내부 VNet에 삽입(배포)될 때 현재의 stv1 컴퓨팅 플랫폼에서 호스트되는 API Management 인스턴스를 stv2 플랫폼으로 마이그레이션하는 단계를 제공합니다. 이 작업을 수행해야 하는지 알아봅니다.

참고 항목

2024년 8월의 새로운 기능: VNet에 삽입된 인스턴스를 마이그레이션하는 데 도움이 되도록 포털의 마이그레이션 옵션이 개선되었습니다! 이제 인스턴스를 원래 위치로 마이그레이션하고 동일한 서브넷과 IP 주소를 유지할 수 있습니다.

VNet 삽입 인스턴스의 경우 다음과 같은 마이그레이션 옵션이 있습니다.

옵션 1: 동일한 서브넷 유지 - 인스턴스를 현재 위치로 마이그레이션하고 인스턴스의 기존 서브넷 구성을 유지합니다. API Management 인스턴스의 원래 VIP 주소가 유지되는지(권장), 아니면 새 VIP 주소가 생성될지를 선택할 수 있습니다.
옵션 2: 새 서브넷으로 변경 - 동일하거나 다른 VNet에 다른 서브넷을 지정하여 인스턴스를 마이그레이션합니다. 마이그레이션 후 필요에 따라 인스턴스의 원래 서브넷으로 다시 마이그레이션합니다. 마이그레이션 프로세스는 인스턴스의 VIP 주소를 변경합니다. 마이그레이션 후에는 새 VIP 주소를 사용하도록 DNS, 방화벽 규칙 및 VNet을 비롯한 모든 네트워크 종속성을 업데이트해야 합니다.

덜 빈번한 특정 조건에서는 동일한 서브넷의 마이그레이션이 불가능하거나 다르게 동작할 수 있습니다. 자세한 내용은 특수 조건 및 시나리오를 참조 하세요.

stv1 플랫폼에 호스트된 VNnet이 삽입되지 않은 API Management를 마이그레이션해야 하는 경우 VNet이 삽입되지 않은 API Management 인스턴스를 stv2 플랫폼으로 마이그레이션을 참조하세요.

Important

stv1 플랫폼에서 호스트되는 API Management 인스턴스에 대한 지원이 중지됩니다. 글로벌 Azure에서 사용 중지 날짜는 2024년 8월 31일입니다. Azure Government 및 21Vianet에서 운영하는 Azure(중국의 Azure)의 경우 사용 중지 날짜는 2025년 2월 24일입니다. stv1 플랫폼에서 호스트되는 인스턴스가 있는 경우 서비스 사용 중지를 방지하려면 사용 중지일 전에 stv2 플랫폼으로 마이그레이션합니다.

주의

API Management 인스턴스를 stv2 플랫폼으로 마이그레이션하는 것은 장기 실행 작업입니다.
stv2로의 마이그레이션은 되돌릴 수 없습니다.

마이그레이션 중 발생하는 작업

stv1에서 stv2로의 API Management 플랫폼 마이그레이션은 기본 컴퓨팅만 업데이트해야 하며 스토리지 계층에 유지되는 서비스/API 구성에는 영향을 주지 않습니다.

업그레이드 프로세스에는 이전 컴퓨팅과 병렬로 새 컴퓨팅을 만드는 작업이 포함되며, 이 작업에는 최대 45분이 걸릴 수 있습니다. 다중 지역 배포 및 서브넷을 두 번 이상 변경하는 시나리오에서는 더 긴 시간을 계획합니다.
Azure Portal의 API Management 상태는 업데이트 중입니다.
특정 마이그레이션 옵션의 경우 VIP 주소를 유지하도록 선택할 수 있으며, 그러지 않으면 새로운 공용 VIP가 생성됩니다.
새 VIP 주소가 생성되는 마이그레이션 시나리오의 경우:
- Azure가 마이그레이션을 관리합니다.
- 사용자 지정 도메인이 사용 중인 경우 게이트웨이 DNS는 여전히 이전 컴퓨팅을 가리킵니다.
- 사용자 지정 DNS를 사용하지 않는 경우 게이트웨이 및 포털 DNS는 새 컴퓨팅을 즉시 가리킵니다.
- 내부 VNet 모드의 인스턴스에서 고객은 DNS를 관리하므로 DNS 항목은 고객이 업데이트할 때까지 이전 컴퓨팅을 계속 가리킵니다.
- 새 컴퓨팅 또는 이전 컴퓨팅을 가리키는 DNS이므로 API에 대한 가동 중지 시간이 없습니다.
- 새 컴퓨팅 서브넷이 백 엔드에 도달할 수 있도록 하려면 방화벽 규칙(있는 경우)을 변경해야 합니다.
- 마이그레이션에 성공하면 짧은 기간 후에 이전 컴퓨팅이 자동으로 서비스 해제됩니다. 포털의 플랫폼 마이그레이션 블레이드를 사용하여 새 서브넷으로 변경할 때 마이그레이션 설정을 사용하도록 설정하여 기존 게이트웨이를 48시간 동안 보존할 수 있습니다. 48시간 지연 옵션은 VNet 삽입 서비스에만 사용할 수 있습니다.

필수 조건

stv1 컴퓨팅 플랫폼에 API Management 인스턴스를 호스트해야 합니다. 인스턴스가 stv1 플랫폼에 호스트되어 있는지 확인하려면 내 API Management 인스턴스를 호스트하는 플랫폼을 알려면 어떻게 할까요?를 참조하세요.
인스턴스는 현재 외부 또는 내부 VNet에 배포해야 합니다.

다른 필수 구성 요소는 다음 섹션의 마이그레이션 옵션과 관련이 있습니다.

옵션 1: 동일한 서브넷 마이그레이션 및 유지

기존 서브넷 구성을 유지한 채로 stv2 플랫폼으로 API Management 인스턴스를 마이그레이션하여 마이그레이션을 간소화할 수 있습니다. Azure Portal의 플랫폼 마이그레이션 블레이드나 Stv2 REST API로 마이그레이션을 사용하여 마이그레이션할 수 있습니다.

필수 조건

네트워크 보안 그룹을 각 서브넷에 연결해야 하며 stv2 플랫폼에서 API Management에 대한 NSG 규칙을 구성해야 합니다. 다음은 최소 연결 설정입니다.
- 포트 443을 통해 Azure Storage로 아웃바운드
- 포트 1433을 통해 Azure SQL로 아웃바운드
- 포트 443을 통해 Azure Key Vault로 아웃바운드
- 포트 6390을 통해 Azure Load Balancer에서 인바운드
- 포트 3443을 통해 ApiManagement 서비스 태그에서 인바운드
- API Management 서비스를 호출하는 클라이언트의 경우 포트 80/443을 통해 인바운드
- 서브넷에서는 Azure Storage, Azure SQL 및 Azure Key Vault에 대해 서비스 엔드포인트를 사용하도록 설정해야 함
각 기존 서브넷의 주소 공간은 마이그레이션 중에 기존 서비스의 복사본을 기존 서비스와 나란히 호스트할 수 있을 만큼 커야 합니다.
기타 네트워크 고려 사항:
- 서브넷에 배포된 API Management 인스턴스에 대해 구성된 자동 크기 조정 규칙을 비활성화합니다. 자동 크기 조정 규칙은 마이그레이션 프로세스를 방해할 수 있습니다.
- 동일한 서브넷에 여러 API Management 인스턴스가 있는 경우 각 인스턴스를 순서대로 마이그레이션합니다. 동일한 서브넷의 여러 플랫폼에서 호스트되는 인스턴스와 관련된 잠재적인 문제를 방지하려면 서브넷의 모든 인스턴스를 즉시 마이그레이션하는 것이 좋습니다.

Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
- 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.
- 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.
- az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

공용 IP 주소 옵션 - 동일한 서브넷 마이그레이션

API Management 인스턴스의 원래 VIP 주소가 유지되는지(권장), 아니면 새 VIP 주소가 생성될지를 선택할 수 있습니다.

가상 IP 주소 유지 - 외부 모드의 VNet에서 VIP 주소를 유지하는 경우 API 요청은 마이그레이션 중에 응답 상태를 유지할 수 있습니다(예상 가동 중지 시간 참조). 내부 모드인 VNet의 경우 임시 가동 중지 시간이 필요합니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 45분 동안 잠깁니다. 마이그레이션 후에는 추가 구성이 필요하지 않습니다.

이 옵션을 사용하면 마이그레이션이 완료된 후 stv1 컴퓨팅이 영구적으로 삭제됩니다. 일시적으로 보존할 수 있는 옵션은 없습니다.

다음 이미지는 IP 주소가 보존될 때 어떤 일이 일어나는지에 대한 개략적인 개요를 보여 줍니다.
새 가상 IP 주소 - 이 옵션을 선택하면 API Management에서 인스턴스에 대한 새 VIP 주소를 생성합니다. API 요청은 마이그레이션 중에도 응답 상태를 유지합니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 30분 동안 잠깁니다. 마이그레이션 후에는 새 VIP 주소를 사용하도록 DNS, 방화벽 규칙 및 VNet을 비롯한 모든 네트워크 종속성을 업데이트해야 합니다.

이 옵션을 사용하면 마이그레이션이 완료된 후 기본적으로 stv1 컴퓨팅이 짧은 기간 동안 유지되므로 마이그레이션된 인스턴스의 유효성을 검사하고 네트워크 및 DNS 구성을 확인할 수 있습니다.

다음 이미지는 새로운 IP 주소가 생성될 때 어떤 일이 일어나는지에 대한 전반적인 개요를 보여 줍니다.

마이그레이션을 위해 미리 만들어진 IP 주소

공용 IP 주소로 접속 가능한 API Management 인스턴스의 경우, API Management는 마이그레이션 프로세스를 위해 공용 IP 주소를 미리 만듭니다. API Management 인스턴스 속성의 JSON 출력에서 미리 만들어진 IP 주소를 찾습니다. customProperties에서 미리 만들어진 IP 주소는 Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps 속성의 값입니다. 다중 지역 배포의 경우, 값은 미리 만들어진 IP 주소의 쉼표로 구분된 목록입니다.

미리 만들어진 IP 주소를 사용하여 마이그레이션 프로세스를 관리합니다.

VIP 주소를 마이그레이션하고 보존하면 원래 IP 주소가 stv2 배포에 할당되기 전에 미리 만들어진 IP 주소가 새 stv2 배포에 일시적으로 할당됩니다. 예를 들어, API Management 인스턴스에 대한 액세스를 제한하는 방화벽 규칙이 있는 경우 미리 만들어진 IP 주소를 허용 목록에 추가하여 마이그레이션 중에 클라이언트 액세스의 연속성을 유지할 수 있습니다. 마이그레이션이 완료된 후 허용 목록에서 미리 만들어진 IP 주소를 제거할 수 있습니다.
마이그레이션하고 새 VIP 주소를 생성하면 미리 만들어진 IP 주소가 마이그레이션 중에 새 stv2 배포에 할당되고 마이그레이션이 완료된 후에도 유지됩니다. 미리 만들어진 IP 주소를 사용하여 DNS 및 방화벽 규칙 등의 네트워크 종속성을 업데이트해 새 IP 주소를 가리키도록 합니다.

예상 가동 중지 시간 및 컴퓨팅 보존

VNet 삽입 인스턴스를 마이그레이션하고 동일한 서브넷 구성을 유지하는 경우 API 게이트웨이에 대한 가동 중지 시간을 최소화하거나 사용하지 않아야 합니다. 다음 표에는 동일한 서브넷을 유지할 때 각 마이그레이션 시나리오에 대한 예상 가동 중지 시간 및 stv1 컴퓨팅 보존이 요약되어 있습니다.

VNet 모드	공용 IP 옵션	예상 가동 중지 시간	`stv1` 컴퓨팅 보존
외부	VIP 유지	가동 중지 시간 없음. 트래픽은 새 `stv2` 배포로 마이그레이션하는 동안 최대 20분 동안 임시 IP 주소에서 제공됩니다.	보존 없음
외부	새 VIP	가동 중지 시간이 없음	네트워크 종속성을 업데이트할 수 있도록 기본적으로 15분 동안 유지됩니다.
내부	VIP 유지	마이그레이션하는 동안 약 20분 동안 가동 중지 시간이 발생하며 기존 IP 주소가 새 `stv2` 배포에 할당됩니다.	보존 없음
내부	새 VIP	가동 중지 시간이 없음	네트워크 종속성을 업데이트할 수 있도록 기본적으로 15분 동안 보존되며 포털을 사용하는 경우 48시간까지 연장할 수 있습니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 설정에서 플랫폼 마이그레이션을 선택합니다.
마이그레이션 옵션 선택에서 동일한 서브넷 유지를 선택합니다.
IP 주소 옵션 선택에서 두 가지 IP 주소 옵션 중 하나를 선택합니다.

참고 항목

VNet이 외부 모드인 경우 마이그레이션 프로세스를 위해 미리 만들어진 공용 IP 주소를 기록해 둡니다. 이 주소를 사용하여 마이그레이션된 인스턴스에 대한 네트워크 연결을 구성합니다.
(내부 모드에서 삽입된 인스턴스와 새 VIP로 마이그레이션하는 경우) 요구 사항에 맞는 시나리오 선택에서 마이그레이션 후 일정 기간 동안 원래 stv1 컴퓨팅을 유지할지 여부에 따라 두 가지 옵션 중 하나를 선택합니다.
서브넷에 대한 자동 검사를 실행하려면 확인을 선택합니다. 문제가 검색되면 서브넷 구성을 조정하고 검사를 다시 실행합니다. DNS 및 방화벽 규칙과 같은 다른 네트워크 종속성은 수동으로 확인합니다.
마이그레이션을 확인하고 마이그레이션 시작을 선택합니다. API Management 인스턴스의 상태가 업데이트 중으로 변경됩니다. 마이그레이션 프로세스를 완료하는 데 약 45분이 소요됩니다. 상태가 온라인으로 변경되면 마이그레이션이 완료된 것입니다.

마이그레이션 스크립트

다음 Azure CLI 명령을 실행하여 Stv2로 마이그레이션 API를 호출하고 API Management 인스턴스 이름과 해당 인스턴스가 만들어진 리소스 그룹 이름으로 표시된 변수를 설정합니다.

참고 항목

bash 셸에 대해 다음 스크립트가 작성되었습니다. PowerShell에서 스크립트를 실행하려면 변수를 설정할 때 변수 이름 앞에 $ 문자를 붙입니다. 예: $APIM_NAME=...

APIM_NAME={name of your API Management instance}
# In PowerShell, use the following syntax: $APIM_NAME={name of your API Management instance}
RG_NAME={name of your resource group}
# Get resource ID of API Management instance
APIM_RESOURCE_ID=$(az apim show --name $APIM_NAME --resource-group $RG_NAME --query id --output tsv)
# Call REST API to migrate to stv2 and preserve VIP address
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "PreserveIp"}'
# Alternate call to migrate to stv2 and change VIP address
# az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "NewIp"}'

API Management 인스턴스의 상태가 업데이트 중으로 변경됩니다. 마이그레이션 프로세스를 완료하는 데 약 45분이 소요됩니다. 상태가 온라인으로 변경되면 마이그레이션이 완료된 것입니다.

참고 항목

API Management 인스턴스가 여러 지역에 배포된 경우 REST API는 단일 호출을 사용하여 인스턴스의 모든 위치에 대한 VNet 설정을 마이그레이션합니다.