Utiliser des plug-ins

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Edge Microgateway v. 3.3.x

Audience

Cet article s'adresse aux opérateurs Edge Microgateway qui souhaitent utiliser les plug-ins existants installés avec la microgateway. Il aborde également en détail les plug-ins de protection contre les pics et de quota (tous deux inclus dans l'installation). Si vous êtes un développeur et que vous souhaitez développer de nouveaux plug-ins, consultez Développer des plug-ins personnalisés.

Qu'est-ce qu'un plug-in Edge Microgateway ?

Un plug-in est un module Node.js qui ajoute des fonctionnalités à Edge Microgateway. Les modules de plug-in suivent un modèle cohérent et sont stockés dans un emplacement connu d'Edge Microgateway, ce qui permet à la passerelle de microservices de les découvrir et de les charger automatiquement. Edge Microgateway inclut plusieurs plug-ins existants. Vous pouvez également créer des plug-ins personnalisés, comme expliqué dans Développer des plug-ins personnalisés.

Plug-ins existants fournis avec Edge Microgateway

Un certain nombre de plug-ins sont fournis avec Edge Microgateway lors de l'installation. Le tableau suivant décrit certains des plug-ins les plus couramment utilisés.

Où trouver les plug-ins existants ?

Les plug-ins existants fournis avec Edge Microgateway se trouvent ici, où [prefix] est le répertoire de préfixe npm. Consultez Où Edge Microgateway est-il installé ? si vous ne trouvez pas ce répertoire.

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

Ajouter et configurer des plug-ins

Suivez ce modèle pour ajouter et configurer des plug-ins :

1. Arrêtez Edge Microgateway.
2. Ouvrez un fichier de configuration Edge Microgateway. Pour en savoir plus sur les options, consultez Modifier la configuration.
3. Ajoutez le plug-in à l'élément plugins:sequence du fichier de configuration, comme suit. Les plug-ins sont exécutés dans l'ordre dans lequel ils apparaissent dans cette liste.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
     level: info
     dir: /var/tmp
     stats_log_interval: 60
  plugins:
     dir: ../plugins
     sequence:   
     - oauth
     - plugin-name

4. Configurez le plug-in. Certains plug-ins comportent des paramètres facultatifs que vous pouvez configurer dans le fichier de configuration. Par exemple, vous pouvez ajouter la strophe suivante pour configurer le plug-in d'arrêt des pics. Pour en savoir plus, consultez Utiliser le plug-in Spike Arrest.

   edgemicro:
     home: ../gateway
     port: 8000
     max_connections: -1
     max_connections_hard: -1
     logging:
       level: info
       dir: /var/tmp
       stats_log_interval: 60
     plugins:
       dir: ../plugins
       sequence:
         - oauth
         - spikearrest
   spikearrest:
      timeUnit: minute
      allow: 10

5. Enregistrez le fichier.
6. Redémarrez ou rechargez Edge Microgateway, selon le fichier de configuration que vous avez modifié.

Configuration spécifique au plug-in

Vous pouvez remplacer les paramètres de plug-in spécifiés dans le fichier de configuration en créant une configuration spécifique au plug-in dans ce répertoire :

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins/config

où [prefix] est le répertoire de préfixe npm. Consultez Où Edge Microgateway est-il installé ? si vous ne trouvez pas ce répertoire.

plugins/<plugin_name>/config/default.yaml. Par exemple, vous pouvez placer ce bloc dans plugins/spikearrest/config/default.yaml. Il remplacera tous les autres paramètres de configuration.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Utiliser le plug-in Spike Arrest

Le plug-in SpikeArrest protège contre les pics de trafic. Il limite le nombre de requêtes traitées par une instance Edge Microgateway.

Ajouter le plug-in Spike Arrest

Consultez Ajouter et configurer des plug-ins.

Exemple de configuration pour l'arrêt des pics

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - spikearrest
spikearrest:
   timeUnit: minute
   allow: 10
   bufferSize: 5

Options de configuration pour l'arrêt des pics

• timeUnit : fréquence à laquelle la fenêtre d'exécution de l'arrêt des pics est réinitialisée. Les valeurs valides sont "second" ou "minute".
• allow : nombre maximal de requêtes autorisées pendant la timeUnit. Consultez également Si vous exécutez plusieurs processus Edge Micro.
• bufferSize : (facultatif, valeur par défaut = 0) si bufferSize > 0, l'arrêt des pics stocke ce nombre de requêtes dans une mémoire tampon. Dès que la prochaine "période" d'exécution se produit, les requêtes mises en mémoire tampon sont traitées en premier. Consultez également Ajouter une zone tampon.

Comment fonctionne SpikeArrest ?

Considérez SpikeArrest comme un moyen de protection générale contre les pics de trafic plutôt que comme un moyen de limiter le trafic à un nombre spécifique de demandes. Vos API et votre backend peuvent gérer une certaine quantité de trafic, tandis que la règle SpikeArrest vous aide à fluidifier le trafic en fonction des volumes généraux que vous souhaitez.

Le comportement à l'exécution de SpikeArrest diffère de ce que l'on pourrait attendre des valeurs littérales par minute ou par seconde que vous entrez.

Par exemple, supposons que vous spécifiiez un débit de 30 requêtes par minute, comme suit :

spikearrest:
   timeUnit: minute
   allow: 30

Lors des tests, on pourrait imaginer envoyer 30 requêtes en une seconde, à condition qu'elles arrivent dans la minute qui suit. Mais ce n'est pas ainsi que la règle s'applique. À bien y réfléchir, 30 requêtes en une seconde pourraient être considérées comme un mini pic dans certains environnements.

Que se passe-t-il donc réellement ? Pour éviter les situations de pics, SpikeArrest lisse le trafic autorisé en divisant vos paramètres en intervalles plus petits, comme suit :

Tarifs à la minute

Les débits par minute sont lissés pour obtenir un nombre de requêtes autorisées par intervalles exprimés en secondes. Par exemple, un taux de 30 requêtes par minute est lissé de la manière suivante :

60 secondes (une minute) / 30 = 2 secondes, soit environ une requête autorisée toutes les deux secondes. Une seconde requête dans un intervalle de deux secondes échouera. Une 31e requête dans un intervalle d'une minute échouera également.

Tarifs à la seconde

Les débits par seconde sont lissés pour obtenir un nombre de requêtes autorisées par intervalles exprimés en millisecondes. Par exemple, un taux de 10 requêtes par seconde est lissé de la manière suivante :

1 000 millisecondes (1 seconde) / 10 = 100 millisecondes d'intervalles, soit environ une requête autorisée toutes les 100 millisecondes . Une deuxième requête dans un intervalle de 100 ms échouera. En outre, une 11e requête dans un intervalle d'une seconde échouera.

Lorsque la limite est dépassée

Si le nombre de requêtes dépasse la limite dans l'intervalle de temps spécifié, la protection contre les pics renvoie le message d'erreur suivant avec un état HTTP 503 :

{"error": "spike arrest policy violated"}

Ajouter un tampon

Vous pouvez ajouter une marge à la règle. Imaginons que vous définissiez la mémoire tampon sur 10. Vous constaterez que l'API ne renvoie pas d'erreur immédiatement lorsque vous dépassez la limite de protection contre les pics. Au lieu de cela, les requêtes sont mises en mémoire tampon (jusqu'au nombre spécifié) et traitées dès que la prochaine fenêtre d'exécution appropriée est disponible. La valeur par défaut de bufferSize est 0.

Si vous exécutez plusieurs processus Edge Micro

Le nombre de requêtes autorisées dépend du nombre de processus de nœud de calcul Edge Micro en cours d'exécution. La protection contre les pics calcule le nombre de requêtes autorisées par processus de nœud de calcul. Par défaut, le nombre de processus Edge Micro est égal au nombre de processeurs de la machine sur laquelle Edge Micro est installé. Toutefois, vous pouvez configurer le nombre de processus de nœud de calcul lorsque vous démarrez Edge Micro à l'aide de l'option --processes sur la commande start. Par exemple, si vous souhaitez que l'arrêt des pics se déclenche à 100 requêtes sur une période donnée, et si vous démarrez Edge Microgateway avec l'option --processes 4, définissez allow: 25 dans la configuration de l'arrêt des pics. En résumé, la règle générale consiste à définir le paramètre de configuration allow sur la valeur "nombre d'arrêts de pics souhaité / nombre de processus".

Utiliser le plug-in de quota

Un quota spécifie le nombre de messages de requête qu'une application est autorisée à envoyer à une API au cours d'une heure, d'une journée, d'une semaine ou d'un mois. Lorsqu'une application atteint sa limite de quota, les appels d'API suivants sont rejetés. Consultez également Quelle est la différence entre l'arrêt des pics et le quota ?

Ajouter le plug-in de quota

Consultez Ajouter et configurer des plug-ins.

Configuration du produit dans Apigee Edge

Vous configurez les quotas dans l'UI Apigee Edge, où vous configurez les produits d'API. Vous devez savoir quel produit contient le proxy compatible avec la micro-passerelle que vous souhaitez limiter avec un quota. Ce produit doit être ajouté à une application de développeur. Lorsque vous effectuez des appels d'API authentifiés à l'aide de clés dans l'application de développeur, le quota est appliqué à ces appels d'API.

1. Connectez-vous au compte de votre organisation Apigee Edge.
2. Dans l'interface utilisateur Edge, ouvrez le produit associé au proxy compatible avec la passerelle de microservices auquel vous souhaitez appliquer le quota.
   1. Dans l'interface utilisateur, sélectionnez Produits dans le menu "Publier".
   2. Ouvrez le produit contenant l'API à laquelle vous souhaitez appliquer le quota.
   3. Cliquez sur Modifier.
   4. Dans le champ "Quota", spécifiez l'intervalle de quota. Par exemple, 100 requêtes par minute. ou 50 000 requêtes toutes les deux heures.
      
      

3. Cliquez sur Enregistrer.
4. Assurez-vous que le produit est ajouté à une application de développeur. Vous aurez besoin des clés de cette application pour effectuer des appels d'API authentifiés.

Exemple de configuration pour le quota

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota

Options de configuration des quotas

Pour configurer le plug-in de quota, ajoutez l'élément quotas à votre fichier de configuration, comme indiqué dans l'exemple suivant :

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
  plugins:
    dir: ../plugins
    sequence:
      - oauth
      - quota
quotas:
    bufferSize:
      hour: 20000
      minute: 500
      month: 1
      default: 10000
    useDebugMpId: true
    failOpen: true
    isHTTPStatusTooManyRequestEnabled: true
...

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: true

edgemicro:
...
quotas:
  isHTTPStatusTooManyRequestEnabled: true

edgemicro:
...
quotas:
  failOpen: true

edgemicro:
...
quotas:
  useDebugMpId: true
...

{
    "allowed": 20,
    "used": 3,
    "exceeded": 0,
    "available": 17,
    "expiryTime": 1570748640000,
    "timestamp": 1570748580323,
    "debugMpId": "6a12dd72-5c8a-4d39-b51d-2c64f953de6a"
}

Comprendre comment les quotas sont comptabilisés

Par défaut, la passerelle de microservices synchronise son compteur de quotas avec Apigee Edge toutes les cinq secondes si l'intervalle de quota est défini sur "minute". Si l'intervalle est défini sur un niveau supérieur à "minute", comme "week" (semaine) ou "month" (mois), la période d'actualisation par défaut est de 1 minute.

Il est important de noter que vous spécifiez les intervalles de quota dans les produits d'API définis sur Apigee Edge. Les intervalles de quota spécifient le nombre de requêtes autorisées par minute, heure, jour, semaine ou mois. Par exemple, le produit A peut avoir un intervalle de quota de 100 requêtes par minute,tandis que le produit B peut avoir un intervalle de quota de 10 000 requêtes par heure.

La configuration YAML du plug-in quota d'Edge Microgateway ne définit pas l'intervalle de quota. Elle permet plutôt d'ajuster la fréquence à laquelle une instance Edge Microgateway locale synchronise son nombre de quotas avec Apigee Edge.

Par exemple, supposons que trois produits d'API soient définis dans Apigee Edge avec les intervalles de quota suivants :

• Le produit A dispose d'un quota de 100 requêtes par minute.
• Le produit B dispose d'un quota de 5 000 requêtes par heure.
• Le produit C dispose d'un quota de 1 000 000 de requêtes par mois.

Compte tenu de ces paramètres de quota, comment configurer le plug-in quota Edge Microgateway ? La bonne pratique consiste à configurer Edge Microgateway avec des intervalles de synchronisation inférieurs aux intervalles de quota définis dans les produits d'API. Exemple :

quotas:
    bufferSize:
      hour: 2000
      minute: 50
      month: 1
      default: 10000

Cette configuration définit les intervalles de synchronisation suivants pour les produits d'API décrits précédemment :

• Le produit A est défini sur l'intervalle "minute". Edge Microgateway se synchronise avec Edge après chaque 50e requête ou toutes les cinq secondes, selon la première échéance atteinte.
• Le produit B est défini sur l'intervalle "heure". Edge Microgateway se synchronise avec Edge toutes les 2 000 requêtes ou toutes les minutes, selon la première occurrence.
• Le produit C est défini sur l'intervalle "mois". Edge Microgateway se synchronise avec Edge après chaque requête ou toutes les minutes, selon la première occurrence.

Chaque fois qu'une instance de microgateway se synchronise avec Edge, le nombre de quotas de la microgateway est défini sur le nombre de quotas récupéré.

Les paramètres bufferSize vous permettent d'ajuster la façon dont le compteur de quota est synchronisé avec Edge. En cas de trafic élevé, les paramètres bufferSize permettent au compteur de mémoire tampon de se synchroniser avant le déclenchement de la synchronisation par défaut basée sur le temps.

Comprendre le champ d'application des quotas

Le nombre de quotas est limité à un environnement dans une organisation. Pour atteindre cette portée, Edge Microgateway crée un identifiant de quota qui combine "org + env + appName + productName".

Utiliser un magasin de stockage Redis pour les quotas

Pour utiliser un magasin de stockage Redis pour les quotas, utilisez la même configuration que celle utilisée pour la fonctionnalité Synchronizer. Voici la configuration de base requise pour utiliser Redis pour le stockage des quotas :

edgemicro:
  redisHost: localhost
  redisPort: 6379
  redisDb: 2
  redisPassword: codemaster

quotas:
  useRedis: true

Tester le plug-in de quota

Lorsque le quota est dépassé, un état HTTP 403 est renvoyé au client, ainsi que le message suivant :

{"error": "exceeded quota"}

Quelle est la différence entre l'arrêt des pics et le quota ?

Il est important de choisir l'outil adapté à la tâche à accomplir. Les règles de quota configurent le nombre de messages de requête qu'une application cliente est autorisée à envoyer à une API pendant une heure, un jour, une semaine ou un mois. La règle de quota applique des limites de consommation aux applications clientes en alimentant un compteur distribué du nombre de requêtes entrantes.

Utilisez une règle de quota pour appliquer des contrats d'entreprise ou des contrats de niveau de service vis-à-vis de développeurs et de partenaires, plutôt que pour la gestion du trafic opérationnel. Par exemple, un quota peut être utilisé pour limiter le trafic à un service sans frais, tout en autorisant l'accès complet aux clients payants.

Utilisez SpikeArrest pour vous protéger contre les pics soudains du trafic de l'API. En général, l'arrêt des pics est utilisé pour prévenir d'éventuelles attaques DDoS ou d'autres attaques malveillantes.