Migrar uma instância de Gerenciamento de API não injetada em uma VNet para a plataforma de computação stv2

APLICA-SE A: Desenvolvedor | Básico | Standard | Premium

Este artigo fornece as etapas para migrar uma instância de Gerenciamento de API hospedada na plataforma de computação stv1 para a plataforma stv2 in-loco quando a instância não está injetada (implantada) em uma VNet externa ou interna. Para esse cenário, migre sua instância usando o portal do Azure ou a API REST Migrar para stv2. Descubra se você precisa fazer isso.

Caso precise migrar uma instância de Gerenciamento de API injetada em uma VNnet hospedada na plataforma stv1, confira Migrar uma instância de Gerenciamento de API injetada em uma VNet para a plataforma stv2.

O que acontece durante a migração?

A migração da plataforma de Gerenciamento de API de stv1 para stv2 envolve a atualização da computação subjacente autônoma e não tem nenhum impacto na configuração de serviço/api persistida na camada de armazenamento. Para uma instância que não está implantada em uma VNet:

• Você pode escolher se o endereço IP virtual (VIP) da instância será alterado ou se o endereço VIP original será preservado.
• O processo de atualização envolve a criação de uma nova computação em paralelo à computação antiga.
• O status do Gerenciamento de API no portal será Atualizando.
• Se você optar por preservar o endereço VIP, a migração incluirá uma etapa adicional para migrar o VIP da computação antiga para a nova computação, durante a qual as APIs não estarão responsivas.
• O Azure gerencia o DNS do ponto de extremidade de gerenciamento e atualiza para a nova computação imediatamente na migração bem-sucedida.
• O DNS do portal e o gateway padrão apontarão para a nova computação imediatamente.
• Se optar por fazer com que sua instância de Gerenciamento de API receba um novo endereço VIP, você precisará atualizar as dependências de rede para usarem o novo endereço VIP.

Pré-requisitos

• Uma instância do Gerenciamento de API hospedada na plataforma de computação stv1. Para confirmar se sua instância está hospedada na plataforma stv1, confira Como posso saber qual plataforma hospeda minha instância de Gerenciamento de API?

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Migrar a instância para a plataforma stv2

Opções de endereço IP público

Você pode escolher se o endereço IP virtual do Gerenciamento de API será alterado ou se o endereço VIP original será preservado.

• Novo endereço IP virtual: se você escolher esse modo, as solicitações de API permanecerão responsivas durante a migração. A configuração de infraestrutura (como domínios personalizados, locais e certificados de AC) será bloqueada por 30 minutos. Após a migração, você precisará atualizar as dependências de rede, incluindo DNS, regras de firewall e VNets para usar o novo endereço VIP.

• Preservar o endereço IP: se você preservar o endereço VIP, as solicitações de API ficarão sem resposta por aproximadamente 15 minutos enquanto o endereço IP for migrado para a nova infraestrutura. A configuração de infraestrutura (como domínios personalizados, locais e certificados de AC) será bloqueada por 45 minutos. Nenhuma configuração adicional é necessária após a migração.

Endereço IP pré-criado para migração

Para as instâncias do Gerenciamento de API que podem ser acessadas por um endereço IP público, o Gerenciamento de API cria previamente um IP público para o processo de migração. Localize o endereço IP pré-criado na saída JSON das propriedades da instância de Gerenciamento de API. Em customProperties, o endereço IP pré-criado é o valor da propriedade Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps. Para uma implantação de várias regiões, o valor é uma lista separada por vírgulas de endereços IP pré-criados.

Use o endereço IP pré-criado (ou endereços) para ajudá-lo a gerenciar o processo de migração:

• Quando você migra e preserva o endereço VIP, o endereço IP pré-criado é atribuído temporariamente à nova implantação stv2, antes que o endereço IP original seja atribuído à implantação stv2. Se você tiver regras de firewall que limitam o acesso à instância de Gerenciamento de API, por exemplo, poderá adicionar o endereço IP pré-criado à lista de permissões para preservar a continuidade do acesso do cliente durante a migração. Após a conclusão da migração, você pode remover o endereço IP pré-criado da lista de permissões.
• Quando você migra e gera um novo endereço VIP, o endereço IP pré-criado é atribuído à nova implantação stv2 durante a migração e persiste após a conclusão da migração. Use o endereço IP pré-criado para atualizar suas dependências de rede, como regras de DNS e firewall, para apontar ao novo endereço IP.

Etapas da migração

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"}'

Verificar migração

Para confirmar se a migração foi bem-sucedida, quando o status for alterado para Online verifique a versão da plataforma da sua instância de Gerenciamento de API. Após uma migração bem-sucedida, o valor será stv2 ou stv2.1.

Reverter automaticamente se a migração falhar

Se ocorrer uma falha durante o processo de migração, a instância será revertida automaticamente para a plataforma stv1. Se a migração for concluída com sucesso (a versão da plataforma da instância aparece como stv2 ou stv2.1 e o status como Online), você não poderá revertê-la para a plataforma stv1.

Para obter ajuda em caso de falha na migração, entre em contato com o Suporte do Azure.

Caso precise da capacidade de revertê-la manualmente, a recomendação é implantar uma nova instância de stv2 lado a lado com sua instância original do Gerenciamento de API.

Atualizar dependências de rede

Após uma migração bem-sucedida para um novo endereço VIP, atualize todas as dependências de rede, incluindo DNS, regras de firewall e VNets, para usar o novo endereço VIP.

Ajuda e suporte

Estamos aqui para ajudar você a migrar para a plataforma stv2 com um mínimo de interrupções nos seus serviços.

Em caso de dúvidas, obtenha respostas rápidas dos especialistas da comunidade no Microsoft Q&A. Se tiver um plano de suporte e precisar de ajuda técnica, crie uma solicitação de suporte.

1. Em Resumo, digite uma descrição do problema, por exemplo, "desativação do stv1".
2. Em Tipo de problema, selecione Técnico.
3. Em Assinatura, selecione sua assinatura.
4. Em Serviço, selecione Meus serviços e, em seguida, Serviço de Gerenciamento de API.
5. Em Recurso, selecione o recurso do Azure para o qual você está criando uma solicitação de suporte.
6. Em Tipo de problema, selecione Administração e Gerenciamento.
7. Em Subtipo de problema, selecione Atualização, Escala ou Alterações de SKU.

Perguntas frequentes

• Quais informações precisamos escolher um caminho de migração?

  • Qual é o modo de rede da instância de Gerenciamento de API?
  • Os domínios personalizados estão configurados?
  • Um firewall está envolvido?
  • Alguma dependência conhecida tomada por upstream/downstream nos IPs envolvidos?
  • É uma implantação em várias regiões?
  • Podemos modificar a instância existente ou uma configuração paralela é necessária?
  • Pode haver tempo de inatividade?
  • A migração pode ser feita em horas que não são de negócios?

• Quais são os pré-requisitos para a migração?

  Para instâncias não injetadas em uma VNet, nenhum pré-requisito é necessário. Se você migrar preservando seu endereço IP público, isso renderizará sua instância de Gerenciamento de API sem resposta por aproximadamente 15 minutos. Talvez não haja nenhum tempo de inatividade se você escolher a opção Novo endereço IP virtual, que disponibiliza um Gerenciamento de API em um novo IP. As instâncias configuradas com um domínio personalizado usando um registro A e/ou tendo dependências de rede no endereço IP virtual público terão um tempo de inatividade quando um novo endereço IP virtual for solicitado.

• A migração causará um tempo de inatividade?

  Para instâncias não injetadas em uma VNet, haverá um tempo de inatividade de aproximadamente 15 minutos somente se você optar por preservar o endereço IP original. No entanto, não haverá tempo de inatividade se você migrar com um novo endereço IP e não tiver nenhuma dependência de rede no novo IP. As dependências de rede incluem nome de domínio personalizado sem um CNAME, lista de permissões de IP, regras de firewall e VNets.

• Podem ocorrer perdas de dados ou de configuração durante ou devido à migração?

  A migração de stv1 para stv2 envolve a atualização da plataforma de computação sozinha e a camada de armazenamento interna não é alterada. Portanto, toda a configuração é segura durante o processo de migração. Isso inclui a identidade gerenciada atribuída pelo sistema que, se habilitada, será preservada.

• Como confirmar se a migração foi concluída e bem-sucedida?

  A migração será considerada completa e bem-sucedida quando o status na página de visão geral indicar Online, com a versão da plataforma sendo stv2 ou stv2.1. Verifique também se o status da rede na folha de rede mostra verde para toda a conectividade necessária.

• Posso fazer a migração usando o portal?

  Sim, a folha de Migração de plataforma no portal do Azure irá orientar você ao longo da migração para as instâncias não injetadas em uma VNet.

• Posso preservar o endereço IP da instância?

  Sim, o endereço IP pode ser preservado, mas haverá um tempo de inatividade de aproximadamente 15 minutos.

• Há um caminho de migração sem modificar a instância existente?

  Sim, você precisa de uma migração lado a lado. Isso significa que você cria uma nova instância de Gerenciamento de API em paralelo com sua instância atual e copia a configuração para a nova instância.

• O que acontece se a migração falhar?

  Se a sua instância de Gerenciamento de API não mostrar a versão da plataforma como stv2 ou stv2.1 e o status como Online após você iniciar a migração, provavelmente ocorreu uma falha. Seu serviço é revertido automaticamente para a instância antiga e nenhuma alteração é feita. Caso tenha problemas (como um status Atualizando mantido por mais de 2 horas), entre em contato com o Suporte do Azure.

• Qual funcionalidade não está disponível durante a migração?

  Para instâncias não injetadas em uma VNet:

  • Se você optou por preservar o endereço IP original, as solicitações de API ficarão não responsivas por aproximadamente 15 minutos enquanto o endereço IP estiver sendo migrado para a nova infraestrutura. A configuração de infraestrutura (como domínios personalizados, locais e certificados de AC) será bloqueada por 45 minutos.
  • Se você optou por migrar para um novo endereço IP, as solicitações de API permanecerão responsivas durante a migração. A configuração de infraestrutura (como domínios personalizados, locais e certificados de AC) é bloqueada por 30 minutos. Após a migração, você precisará atualizar as dependências de rede, incluindo DNS, regras de firewall e VNets para usar o novo endereço VIP.

• Quanto tempo a migração levará?

  A duração esperada para toda a migração é de aproximadamente 45 minutos. O indicador para verificar se a migração já foi concluída é conferir se o status da instância voltou a ser Online e não Atualizando. Se aparecer como Atualizando por mais de 2 horas, entre em contato com o Suporte do Azure.

• Posso reverter a migração, se necessário?

  Se houver uma falha durante o processo de migração, a instância será revertida automaticamente para a plataforma stv1. No entanto, após o serviço ter sido migrado com sucesso, você não poderá revertê-lo para a plataforma stv1.

• Existe alguma alteração necessária em domínios personalizados/zonas DNS privadas?

  Para instâncias não injetadas em uma VNet, nenhuma alteração será necessária se o IP for preservado. Se optar por um novo IP, os domínios personalizados que se referem ao IP deverão ser atualizados.

• Minha instância stv1 está implantada em várias regiões do Azure (multirregião). Como fazer para atualizar para o stv2?

  Para um Gerenciamento de API que não estiver injetado em uma VNet, siga as etapas de migração usando o portal ou a CLI do Azure. Todas as regiões serão migradas para stv2.

• Em que devemos pensar no caso de gateways auto-hospedados?

  Você não precisa fazer nada em seus gateways auto-hospedados. Você só precisa migrar instâncias de Gerenciamento de API em execução no Azure que são afetadas pela desativação da plataforma stv1. Observe que pode haver um novo IP para o ponto de extremidade de configuração da instância de Gerenciamento de API e todas as restrições de rede fixadas ao IP devem ser atualizadas.

• Como o portal do desenvolvedor é afetado pela migração?

  Não há nenhum impacto no portal do desenvolvedor. Se domínios personalizados forem usados, o registro DNS deverá ser atualizado com o IP efetivo, após a migração. No entanto, se os domínios padrão estiverem em uso, eles serão atualizados automaticamente na migração bem-sucedida. Não há tempo de inatividade para o portal do desenvolvedor durante a migração.

• Há algum impacto no custo depois de migrarmos para o stv2?

  O modelo de cobrança permanece o mesmo para stv2 e não haverá nenhum custo extra gerado durante e após a migração.

• Quais permissões RBAC são necessárias para a migração da stv1 para a stv2?

  O usuário/processo que estiver realizando a migração precisa ter acesso de gravação na instância de Gerenciamento de API.

Conteúdo relacionado

• Como saber qual plataforma hospeda minha instância de Gerenciamento de API?

• Benefícios da plataforma de computação stv2 para o Gerenciamento de API

• desativação da plataforma stv1 – Azure global (agosto de 2024)

• desativação da plataforma stv1 – Azure Governamental e Azure operados pela 21Vianet (fevereiro de 2025)