VNet이 삽입되지 않은 API Management 인스턴스를 stv2 컴퓨팅 플랫폼으로 마이그레이션

적용 대상: 개발자 | 기본 | 표준 | 프리미엄

이 문서에서는 인스턴스가 외부 또는 현재 위치 VNet에 삽입(배포)되지 않은 경우 stv1 컴퓨팅 플랫폼에서 호스트되는 API Management 인스턴스를 stv2 플랫폼으로 마이그레이션하는 단계를 제공합니다. 이 시나리오에서는 Azure Portal 또는 stv2로 마이그레이션 REST API를 사용하여 인스턴스를 마이그레이션합니다. 이 작업을 수행해야 하는지 알아봅니다.

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

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

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

• 인스턴스의 VIP 주소를 변경할지, 아니면 원래 VIP 주소를 유지할지 선택할 수 있습니다.
• 업그레이드 프로세스에는 이전 컴퓨팅과 동시에 새 컴퓨팅을 만드는 작업이 포함됩니다.
• 포털의 API Management 상태는 업데이트 중입니다.
• VIP 주소를 유지하기로 선택한 경우 마이그레이션에는 API가 응답하지 않는 동안 VIP를 마이그레이션 컴퓨팅에서 새 컴퓨팅으로 이동하는 추가 단계가 포함됩니다.
• Azure는 관리 엔드포인트 DNS를 관리하며, 마이그레이션이 성공하며 즉시 새 컴퓨팅으로 업데이트됩니다.
• 기본 게이트웨이와 포털 DNS는 즉시 새 컴퓨팅을 가리킵니다.
• API Management 인스턴스가 새 VIP 주소를 받도록 선택한 경우 새 VIP 주소를 사용하도록 네트워크 종속성을 업데이트해야 합니다.

필수 조건

• stv1 컴퓨팅 플랫폼에 API Management 인스턴스를 호스트해야 합니다. 인스턴스가 stv1 플랫폼에 호스트되어 있는지 확인하려면 내 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를 실행합니다.

인스턴스를 stv2 플랫폼으로 마이그레이션

공용 IP 주소 옵션

API Management의 가상 IP 주소를 변경할지, 아니면 원래 VIP 주소를 유지할지 선택할 수 있습니다.

• 새 가상 IP 주소 - 이 모드를 선택하면 마이그레이션 중에 API 요청이 응답성을 유지합니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 30분 동안 잠깁니다. 마이그레이션 후에는 새 VIP 주소를 사용하도록 DNS, 방화벽 규칙 및 VNet을 비롯한 모든 네트워크 종속성을 업데이트해야 합니다.

• IP 주소 보존 - VIP 주소를 보존하면 IP 주소가 새 인프라로 마이그레이션되는 동안 API 요청이 약 15분 동안 응답하지 않습니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 45분 동안 잠깁니다. 마이그레이션 후에는 추가 구성이 필요하지 않습니다.

마이그레이션을 위한 미리 만들어진 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 주소를 가리키도록 합니다.

마이그레이션 단계

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 인스턴스의 플랫폼 버전을 확인합니다. 마이그레이션에 성공하면 값은 stv2 또는 stv2.1입니다.

마이그레이션이 실패할 경우 자동으로 되돌리기

마이그레이션 프로세스 중에 오류가 발생할 경우 인스턴스가 자동으로 stv1 플랫폼으로 되돌아갑니다. 마이그레이션이 성공적으로 완료되면(인스턴스의 플랫폼 버전이 stv2 또는 stv2.1로 표시되고 상태가 온라인으로 표시됨) stv1 플랫폼으로 롤백할 수 없습니다.

마이그레이션이 실패하는 경우 도움을 받으려면 Azure 지원에 문의하세요.

수동으로 롤백하는 기능이 필요한 경우 새 stv2 인스턴스를 원본 API Management 인스턴스와 병렬 배포하는 것이 좋습니다.

네트워크 종속성 업데이트

새 VIP 주소로 성공적으로 마이그레이션한 후 새 VIP 주소를 사용하도록 DNS, 방화벽 규칙 및 VNet을 포함한 모든 네트워크 종속성을 업데이트합니다.

도움말 및 지원 

서비스 중단을 최소화하면서 stv2 플랫폼으로 마이그레이션할 수 있도록 도와드리겠습니다.

질문이 있는 경우 Microsoft Q&A에서 커뮤니티 전문가로부터 빠른 답변을 가져오세요. 지원 계획이 있고 기술 지원이 필요한 경우 지원 요청을 만드세요.

1. 요약의 경우 문제에 대한 설명(예: "stv1 사용 중지")을 입력합니다.
2. 문제 형식에서 기술적을 선택합니다.
3. 구독 아래에서 구독을 선택합니다.
4. 서비스에서 내 서비스를 선택한 다음, API Management 서비스를 선택합니다.
5. 리소스에서 지원 요청을 만드는 Azure 리소스를 선택합니다.
6. 문제 유형에 대해 운영 및 관리를 선택합니다.
7. 문제 하위 형식의 경우 업그레이드, 크기 조정 또는 SKU 변경 내용을 선택합니다.

자주 묻는 질문

• 마이그레이션 경로를 선택하려면 어떤 정보가 필요한가요?

  • API Management 인스턴스의 네트워크 모드는 무엇인가요?
  • 사용자 지정 도메인이 구성되어 있나요?
  • 방화벽이 관련되어 있나요?
  • 관련된 IP의 업스트림/다운스트림에서 사용하는 알려진 종속성이 있나요?
  • 다중 지역 배포인가요?
  • 기존 인스턴스를 수정할 수 있나요, 아니면 병렬 설정이 필요한가요?
  • 가동 중지 시간이 있을 수 있나요?
  • 업무 외 시간에 마이그레이션을 수행할 수 있나요?

• 마이그레이션의 필수 조건은 무엇인가요?

  VNet이 삽입되지 않은 인스턴스의 경우 필요한 필수 조건이 없습니다. 공용 IP 주소를 유지하여 마이그레이션하는 경우 약 15분 동안 API Management 인스턴스가 응답하지 않게 렌더링됩니다. 새 IP에서 API Management를 사용할 수 있도록 하는 새 가상 IP 주소 옵션을 선택하면 가동 중지 시간이 발생하지 않을 수 있습니다. A 레코드를 사용하거나 공용 가상 IP 주소에 대한 네트워크 종속성을 갖는 사용자 지정 도메인으로 구성된 인스턴스에는 새 가상 IP 주소가 요청될 때 가동 중지 시간이 발생합니다.

• 마이그레이션으로 인해 가동 중지 시간이 발생하나요?

  VNet이 삽입되지 않은 인스턴스의 경우 원래 IP 주소를 유지하도록 선택한 경우에만 약 15분의 가동 중지 시간이 발생합니다. 그러나 새 IP 주소로 마이그레이션하고 새 IP에 대한 네트워크 종속성이 없으면 가동 중지 시간이 없습니다. 네트워크 종속성에는 CNAME이 없는 사용자 지정 도메인 이름, IP 허용 목록, 방화벽 규칙 및 VNet이 포함됩니다.

• 마이그레이션 중에 데이터 또는 구성이 손실될 수 있나요?

  stv1을 stv2로 마이그레이션하려면 컴퓨팅 플랫폼만 업데이트해야 하며 내부 스토리지 계층은 변경되지 않습니다. 따라서 마이그레이션 프로세스 중에는 모든 구성이 안전합니다. 여기에는 사용하도록 설정된 경우 유지되는 시스템 할당 관리 ID가 포함됩니다.

• 마이그레이션이 완료되고 성공했는지 확인하려면 어떻게 해야 하나요?

  개요 페이지의 상태가 플랫폼 버전 stv2 또는 stv2.1과 함께 온라인으로 표시되는 경우 마이그레이션은 완전하고 성공적인 것으로 간주됩니다. 또한 네트워크 블레이드의 네트워크 상태가 모든 필수 연결에 대해 녹색으로 표시되는지 확인합니다.

• 포털을 사용하여 마이그레이션을 수행할 수 있나요?

  예, Azure Portal의 플랫폼 마이그레이션 블레이드는 VNet이 삽입되지 않은 인스턴스에 대한 마이그레이션을 안내합니다.

• 인스턴스의 IP 주소를 유지할 수 있나요?

  예, IP 주소는 보존될 수 있지만 약 15분의 가동 중지 시간이 발생합니다.

• 기존 인스턴스를 수정하지 않는 마이그레이션 경로가 있나요?

  예, 병렬 마이그레이션이 필요합니다. 즉, 현재 인스턴스와 병렬로 새 API Management 인스턴스를 만들고 구성을 새 인스턴스에 복사합니다.

• 마이그레이션이 실패하면 어떻게 되나요?

  마이그레이션을 시작한 후 API Management 인스턴스가 플랫폼 버전을 stv2 또는 stv2.1로, 상태를 온라인으로 표시하지 않으면 실패했을 수 있습니다. 서비스는 자동으로 이전 인스턴스로 롤백되며 변경되지 않습니다. 문제가 있는 경우(예: 상태가 2시간 이상 업데이트 중으로 표시되는 경우) Azure 지원에 문의하세요.

• 마이그레이션 중에 사용할 수 없는 기능은 무엇인가요?

  VNet이 삽입되지 않은 인스턴스의 경우:

  • 원래 IP 주소를 유지하기로 선택한 경우: IP 주소가 새 인프라로 마이그레이션되는 동안 API 요청은 약 15분 동안 응답하지 않습니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 45분 동안 잠깁니다.
  • 새 IP 주소로 마이그레이션하도록 선택한 경우: API 요청은 마이그레이션 중에 응답성을 유지합니다. 인프라 구성(예: 사용자 지정 도메인, 위치 및 CA 인증서)은 30분 동안 잠깁니다. 마이그레이션 후에는 새 VIP 주소를 사용하도록 DNS, 방화벽 규칙 및 VNet을 비롯한 모든 네트워크 종속성을 업데이트해야 합니다.

• 마이그레이션은 얼마나 걸리나요?

  전체 마이그레이션의 예상 기간은 약 45분입니다. 마이그레이션이 이미 수행되었는지 확인하는 표시기는 인스턴스 상태가 업데이트 중이 아닌 온라인으로 복귀되었는지 확인합니다. 상태가 2시간 이상 업데이트 중이면 Azure 지원 서비스에 문의하세요.

• 필요한 경우 마이그레이션을 롤백할 수 있나요?

  마이그레이션 프로세스 중에 오류가 발생하면 인스턴스가 자동으로 stv1 플랫폼으로 롤백됩니다. 그러나 서비스가 성공적으로 마이그레이션된 후에는 stv1 플랫폼으로 롤백할 수 없습니다.

• 사용자 지정 도메인/프라이빗 DNS 영역에 변경이 필요하나요?

  VNet이 아닌 삽입된 인스턴스의 경우 IP가 보존되면 변경이 필요하지 않습니다. 새 IP를 선택하는 경우 IP를 참조하는 사용자 지정 도메인을 업데이트해야 합니다.

• 내 stv1 인스턴스는 여러 Azure 지역(다중 지역)에 배포됩니다. stv2로 업그레이드하려면 어떻게 해야 하나요?

  VNet에 삽입되지 않는 API Management의 경우 포털 또는 Azure CLI를 사용하여 마이그레이션 단계를 따릅니다. 모든 지역이 stv2로 마이그레이션됩니다.

• 자체 호스팅 게이트웨이에 대해 무엇을 고려해야 하나요?

  자체 호스팅 게이트웨이에서는 아무 것도 수행할 필요가 없습니다. stv1 플랫폼 사용 중지의 영향을 받는 Azure에서 실행되는 API Management 인스턴스를 마이그레이션하기만 하면 됩니다. API Management 인스턴스의 구성 엔드포인트에 대한 새 IP가 있을 수 있으며 IP에 고정된 네트워킹 제한을 업데이트해야 합니다.

• 개발자 포털은 마이그레이션 시 어떻게 영향을 받나요?

  개발자 포털에는 영향을 주지 않습니다. 사용자 지정 도메인을 사용하는 경우 마이그레이션 후에 DNS 레코드를 유효한 IP로 업데이트해야 합니다. 그러나 기본 도메인이 사용 중인 경우 마이그레이션 성공 시 자동으로 업데이트됩니다. 마이그레이션하는 동안 개발자 포털에 대한 가동 중지 시간이 없습니다.

• stv2로 마이그레이션한 후 비용이 영향을 받나요?

  stv2에 대한 청구 모델은 동일하게 유지되며 마이그레이션 도중과 마이그레이션 후에 더 이상 비용이 발생하지 않습니다.

• stv1에서 stv2로 마이그레이션하려면 어떤 RBAC 권한이 필요하나요?

  마이그레이션을 수행하는 사용자/프로세스에는 API Management 인스턴스에 대한 쓰기 권한이 필요합니다.

관련 콘텐츠

• 내 API Management 인스턴스를 호스트하는 플랫폼을 알려면 어떻게 할까요?

• API Management를 위한 stv2 컴퓨팅 플랫폼의 이점

• stv1 플랫폼 사용 중지 - 글로벌 Azure(2024년 8월)

• stv1 플랫폼 사용 중지 - 21Vianet에서 운영하는 Azure Government 및 Azure(2025년 2월)