Guide de migration de passerelle auto-hébergée

  • Article

S’APPLIQUE À : Développeur | Premium

Cet article explique comment migrer des déploiements de passerelle auto-hébergée existants vers une passerelle auto-hébergée v2.

Important

La prise en charge des images conteneur de la passerelle auto-hébergée version 0 et version 1 d’Azure Gestion des API se termine le 1er octobre 2023, ainsi que son API de configuration correspondante v1. En savoir plus dans notre documentation de dépréciation

Nouveautés

Comme nous nous efforçons de faciliter le déploiement de notre passerelle auto-hébergée par les clients, nous avons introduit une nouvelle API de configuration qui supprime la dépendance sur stockage Azure, sauf si vous utilisez l’inspecteur d’API ou des quotas.

La nouvelle API de configuration permet aux clients d’adopter, de déployer et d’exploiter plus facilement notre passerelle auto-hébergée dans leur infrastructure existante.

Nous avons introduit de nouvelles balises d’image conteneur pour permettre aux clients de choisir la meilleure façon d’essayer notre passerelle et de la déployer en production.

Pour aider les clients à exécuter notre passerelle en production, nous avons étendu nos conseils de production pour comprendre la façon de mettre à l’échelle automatiquement la passerelle et de la déployer pour une haute disponibilité dans votre cluster Kubernetes.

En savoir plus sur la connectivité de notre passerelle, nos nouvelles exigences en matière d’infrastructure et ce qui se passe si la connectivité est perdue dans cet article.

Prérequis

Avant de pouvoir migrer vers la passerelle auto-hébergée v2, vous devez vous assurer que votre infrastructure répond aux exigences.

Migrer vers une passerelle auto-hébergée v2

La migration à partir d’une passerelle auto-hébergée v2 nécessite quelques petites étapes :

  1. Utiliser une nouvelle image conteneur
  2. Utiliser la nouvelle API de configuration
  3. Respecter les exigences de sécurité minimales

Image conteneur

Modifiez la balise d’image dans vos scripts de déploiement pour utiliser 2.0.0 ou une version ultérieure.

Vous pouvez également choisir l’une de nos autres balises d’image conteneur.

Vous trouverez ici une liste complète des balises disponibles ou nous trouver sur Docker Hub.

Utiliser la nouvelle API de configuration

Pour migrer vers la passerelle auto-hébergée v2, les clients doivent utiliser notre nouvelle API de configuration v2.

Actuellement, Azure API Management fournit les API de configuration suivantes pour la passerelle auto-hébergée :

Service de configuration URL Pris en charge Spécifications
v2 {name}.configuration.azure-api.net Yes Lien
v1 {name}.management.azure-api.net/subscriptions/{sub-id}/resourceGroups/{rg-name}/providers/Microsoft.ApiManagement/service/{name}?api-version=2021-01-01-preview Non Lien

Le client doit utiliser la nouvelle API de configuration v2 en modifiant ses scripts de déploiement pour utiliser la nouvelle URL et répondre aux exigences de l’infrastructure.

Important

  • Les noms d’hôte DNS doivent pouvoir être résolus en adresses IP et les adresses IP correspondantes doivent être accessibles. Cela peut nécessiter une configuration supplémentaire si vous utilisez un DNS privé, un réseau virtuel interne ou d’autres exigences d’infrastructure.

Sécurité

Suites de chiffrement TLS disponibles

Lors du lancement, la passerelle auto-hébergée v2.0 n’a utilisé qu’une partie des suites de chiffrement utilisées par v1.x. Depuis la version 2.0.4, nous avons ramené toutes les suites de chiffrement prises en charge par v1.x.

Vous pouvez en savoir plus sur les suites de chiffrement utilisées dans cet article ou utiliser v2.1.1 pour contrôler les suites de chiffrement à utiliser.

Respecter les exigences de sécurité minimales

Au démarrage, la passerelle auto-hébergée prépare les certificats d’autorité de certification qui seront utilisés. Cela nécessite que le conteneur de passerelle s’exécute avec au moins l’ID d’utilisateur 1001 et ne peut pas utiliser le système de fichiers en lecture seule.

Lors de la configuration d’un contexte de sécurité pour le conteneur dans Kubernetes, les éléments suivants sont requis au minimum :

securityContext:
  runAsNonRoot: true
  runAsUser: 1001
  readOnlyRootFilesystem: false

Cependant, dès le 2.0.3, la passerelle auto-hébergée peut s’exécuter en tant que non-racine dans Kubernetes, ce qui permet aux clients d’exécuter la passerelle en toute sécurité.

Voici un exemple de contexte de sécurité pour la passerelle auto-hébergée :

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

Avertissement

L’exécution de la passerelle auto-hébergée avec le système de fichiers en lecture seule (readOnlyRootFilesystem: true) n’est pas prise en charge.

Évaluation de l’impact avec Azure Advisor

Pour faciliter la migration, nous avons introduit de nouvelles recommandations Azure Advisor :

  • Utilisez la recommandation v2 de passerelle auto-hébergée : identifie les instances d’Azure Gestion des API où l’utilisation de la passerelle auto-hébergée v0.x ou v1.x a été identifiée.
  • Utilisez l’API de configuration v2 pour les passerelles auto-hébergées recommandation : identifie les instances d’Azure Gestion des API où l’utilisation de l’API de configuration v1 pour la passerelle auto-hébergée a été identifiée.

Nous recommandons vivement aux clients d’utiliser la vue d’ensemble « Toutes les recommandations » dans Azure Advisor pour déterminer si une migration est requise. Utilisez les options de filtrage pour voir si l’une des recommandations ci-dessus est présente.

Utiliser Azure Resource Graph pour identifier les instances Gestion des API Azure

Cette requête Azure Resource Graph vous fournit une liste des instances Gestion des API Azure impactées :

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"

Limitations connues

Voici une liste des limitations connues pour la passerelle auto-hébergée v2 :

  • L’API de configuration v2 ne prend pas en charge les noms de domaine personnalisés

Étapes suivantes