Guia de migração de gateway auto-hospedado

  • Artigo

APLICA-SE A: Desenvolvedor | Premium

Este artigo explica como migrar implantações de gateway auto-hospedado existentes para o gateway auto-hospedado v2.

Importante

O suporte para as imagens de contêiner do gateway auto-hospedado versão 0 e versão 1 do Gerenciamento de API do Azure termina em 1º de outubro de 2023, acompanhado da API de Configuração correspondente v1. Saiba mais em nossa documentação de reprovação

Novidades

Conforme nos esforçamos para facilitar a implantação do gateway auto-hospedado pelos clientes, introduzimos uma nova API de configuração que remove a dependência do Armazenamento do Microsoft Azure, a menos que você esteja usando o inspetor de API ou cotas.

A nova API de configuração permite que os clientes adotem, implantem e operem mais facilmente nosso gateway auto-hospedado na infraestrutura existente deles.

Introduzimos novas marcas de imagem de contêiner para permitir que os clientes escolham a melhor maneira de experimentar nosso gateway e implantá-lo em produção.

Para ajudar os clientes a executar nosso gateway em produção, estendemos nossas diretrizes de produção para abordar como dimensionar automaticamente o gateway e implantá-lo para alta disponibilidade no cluster do Kubernetes.

Saiba mais neste artigo sobre a conectividade do nosso gateway, nossos novos requisitos de infraestrutura e o que acontece se a conectividade for perdida.

Pré-requisitos

Antes de migrar para o gateway auto-hospedado v2, você precisa garantir que sua infraestrutura atenda aos requisitos.

Como migrar para o gateway auto-hospedado v2

A migração para o gateway auto-hospedado v2 requer que algumas etapas pequenas sejam realizadas:

  1. Usar uma nova imagem de contêiner
  2. Usar a nova API de configuração
  3. Atender a requisitos mínimos de segurança

Imagem do contêiner

Altere a marca de imagem em seus scripts de implantação para usar 2.0.0 ou acima.

Como alternativa, escolha uma de nossas outras marcas de imagem de contêiner.

Você pode encontrar uma lista completa de marcas disponíveis aqui ou nos encontrar no Docker Hub.

Usar a nova API de configuração

Para migrar para o gateway auto-hospedado v2, os clientes precisam usar nossa nova API de Configuração v2.

Atualmente, o Gerenciamento de API do Azure fornece as seguintes APIs de Configuração para gateway auto-hospedado:

Serviço de Configuração URL Com suporte Requisitos
v2 {name}.configuration.azure-api.net Sim Link
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview Não Link

O cliente precisa usar a nova API de Configuração v2 alterando os próprios scripts de implantação para usar a nova URL e atender aos requisitos de infraestrutura.

Importante

  • Os nomes de host DNS precisam ser resolvíveis para endereços IP e os endereços IP correspondentes precisam estar acessíveis. Isso pode exigir uma configuração adicional caso você esteja usando um DNS privado, uma VNet interna ou outros requisitos de infraestrutura.

Segurança

Pacotes de criptografia TLS disponíveis

Na inicialização, o gateway auto-hospedado v2.0 usava apenas um subconjunto dos conjuntos de criptografia que a v1.x estava usando. A partir da v2.0.4, trouxemos de volta todos os conjuntos de criptografias suportados pela v1.x.

Você pode conhecer melhor os pacotes de criptografia usados neste artigo ou usar a v2.1.1 para controlar quais pacotes de criptografia usar.

Atender aos requisitos mínimos de segurança

Durante a inicialização, o gateway auto-hospedado preparará os certificados de AC que serão usados. Isso requer que o contêiner de gateway seja executado com pelo menos a ID de usuário 1001 e não pode usar o sistema de arquivos somente leitura.

Ao configurar um contexto de segurança para o contêiner no Kubernetes, existem os seguintes requisitos mínimos:

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

No entanto, da versão 2.0.3 em diante, o gateway auto-hospedado é capaz de ser executado como não raiz no Kubernetes, permitindo que os clientes executem o gateway com mais segurança.

Confira um exemplo do contexto de segurança para o gateway auto-hospedado:

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

Aviso

Não há suporte para executar o gateway auto-hospedado com sistema de arquivos somente leitura (readOnlyRootFilesystem: true).

Avaliar o impacto com o Assistente do Azure

Para facilitar a migração, apresentamos novas recomendações do Assistente do Azure:

  • Usar a recomendação de gateway auto-hospedado v2: identifica instâncias de Gerenciamento de API do Azure em que o uso do gateway auto-hospedado v0.x ou v1.x foi identificado.
  • Usar a API de Configuração v2 para recomendação de gateways auto-hospedados: identifica instâncias de Gerenciamento de API do Azure em que o uso da API de Configuração v1 para gateway auto-hospedado foi identificado.

É altamente recomendável que os clientes usem a visão geral de "Todas as Recomendações" no Assistente do Azure para determinar se uma migração é necessária. Use as opções de filtragem para ver se uma das recomendações acima está presente.

Use o Azure Resource Graph para identificar instâncias do Gerenciamento de API do Azure

Esta consulta do Azure Resource Graph fornece uma lista de instâncias do Gerenciamento de API do Azure afetadas:

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"

Limitações conhecidas

Aqui está uma lista de limitações conhecidas para o gateway auto-hospedado v2:

  • A API de configuração v2 não dá suporte a nomes de domínio personalizados

Próximas etapas