Utiliser des plug-ins

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Edge Microgateway version 3.2.x

Audience

Cette rubrique est destinée aux opérateurs Edge Microgateway qui souhaitent utiliser les plug-ins existants installés avec la micropasserelle. Elle décrit également en détail les plug-ins d'arrêt des pics et de quota (tous deux inclus dans l'installation). Si vous êtes 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 micropasserelle de les détecter et de les charger automatiquement. Edge Microgateway inclut plusieurs plug-ins existants et vous pouvez également créer des plug-ins personnalisés, comme expliqué dans la section Développer des plug-ins personnalisés.

Plug-ins existants fournis avec Edge Microgateway

Plusieurs plug-ins existants sont fournis avec Edge Microgateway lors de l'installation. Exemples:

Où trouver les plug-ins existants ?

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

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

Ajouter et configurer des plug-ins

Pour ajouter et configurer des plug-ins, procédez comme suit:

1. Arrêtez Edge Microgateway.
2. Ouvrez un fichier de configuration Edge Microgateway. Pour en savoir plus sur les options, consultez Apporter des modifications de 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 stanza suivante pour configurer le plug-in d'arrêt des pics. Pour en savoir plus, consultez la section Utiliser le plug-in d'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
   

5. Enregistrez le fichier.
6. Redémarrez ou actualisez Edge Microgateway, en fonction du 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 la section Où est installé Edge Microgateway 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 afin qu'il remplace tous les autres paramètres de configuration.

spikearrest:
   timeUnit: hour   
   allow: 10000   
   buffersize: 0

Utiliser le plug-in d'arrêt des pics

Le plug-in d'arrêt des pics vous 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 d'arrêt des pics

Consultez la section 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 de réinitialisation de la fenêtre d'exécution d'arrêt des pics. Les valeurs valides sont les secondes ou les minutes.
• allow: nombre maximal de requêtes autorisées pour l'élément timeUnit. Consultez également la section 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 un tampon. Dès que la prochaine "fenêtre" d'exécution se produit, les requêtes mises en mémoire tampon seront traitées en premier. Consultez également la section Ajouter un tampon.

Comment l'arrêt des pics fonctionne-t-il ?

Considérez l'arrêt des pics comme un moyen de se protéger généralement contre les pics de trafic plutôt que comme un moyen de limiter le trafic à un nombre spécifique de requêtes. Vos API et votre backend peuvent gérer une certaine quantité de trafic, et la règle d'arrêt des pics vous aide à fluidifier le trafic jusqu'aux volumes généraux souhaités.

Le comportement d'arrêt des pics d'exécution diffère de ce que vous pourriez vous attendre à voir des valeurs littérales par minute ou par seconde que vous saisissez.

Par exemple, supposons que vous spécifiez un taux de 30 requêtes par minute, comme ceci:

spikearrest:
   timeUnit: minute
   allow: 30

Lors des tests, vous pourriez penser que vous pouvez envoyer 30 requêtes en une seconde, à condition qu'elles arrivent dans la minute qui suit. Mais ce n’est pas ainsi que la stratégie applique le paramètre. 30 requêtes en une seconde peuvent être considérées comme un mini pic dans certains environnements.

Que se passe-t-il donc réellement ? Pour éviter tout comportement semblable à celui des pics, l'arrêt des pics lisse le trafic autorisé en divisant vos paramètres en intervalles plus petits, comme suit:

Tarifs à la minute

Les taux par minute sont lissés en intervalles de secondes autorisés pour les requêtes. Par exemple, 30 requêtes par minute sont lissées comme suit:

60 secondes (1 minute) / 30 = intervalles de deux secondes, soit environ 1 requête autorisée toutes les deux secondes. Toute deuxième requête en moins de deux secondes échouera. De plus, toute 31e requête dans une minute échouera.

Tarifs à la seconde

Les taux par seconde sont lissés dans les requêtes autorisées en intervalles de quelques millisecondes. Par exemple, 10 requêtes par seconde sont lissées comme suit:

1 000 millisecondes (1 seconde) / 10 = intervalles de 100 millisecondes, soit environ 1 requête autorisée toutes les 100 millisecondes . Une deuxième requête dans un intervalle de 100 ms échouera. En outre, toute 11e requête dans 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é, l'arrêt du pic renvoie ce message d'erreur avec l'état HTTP 503:

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

Ajouter un tampon

Vous avez la possibilité d'ajouter un tampon à la stratégie. 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 d'arrêt du pic. À la place, les requêtes sont mises en mémoire tampon (jusqu'au nombre spécifié) et sont 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œuds de calcul Edge Micro en cours d'exécution. L'arrêt des pics calcule le nombre autorisé de requêtes par processus de nœud de calcul. Par défaut, le nombre de processus Edge Micro est égal au nombre de processeurs sur 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 de la commande start. Par exemple, si vous souhaitez que l'arrêt des pics se déclenche pour 100 requêtes au cours d'une période donnée et que vous démarrez Edge Microgateway avec l'option --processes 4, définissez allow: 25 dans la configuration d'arrêt des pics. En résumé, la règle d'or 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 en une heure, une journée, une semaine ou un mois. Lorsqu'une application atteint sa limite de quota, les appels d'API suivants sont rejetés. Consultez également la section Quelle est la différence entre l'arrêt des pics et le quota.

Ajouter le plug-in de quota

Consultez la section Ajouter et configurer des plug-ins.

Configuration du produit dans Apigee Edge

Vous configurez des quotas dans l'interface utilisateur d'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 à l'aide d'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 du développeur, le quota est appliqué à ces appels d'API.

1. Connectez-vous à votre compte d'organisation Apigee Edge.
2. Dans l'interface utilisateur Edge, ouvrez le produit associé au proxy compatible avec la micro-passerelle 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 a été 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 les quotas

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
...

quotas:
 bufferSize:
  minute: 500
  default: 10000
 useDebugMpId: true
 failOpen: 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"
}

Compréhension du mode de comptabilisation des quotas

Par défaut, la micropasserelle synchronise son compteur de quota avec Apigee Edge toutes les 5 secondes si l'intervalle de quota est défini sur "minutes". Si l'intervalle est défini sur un niveau supérieur à "minute", tel que "semaine" ou "mois", la période d'actualisation par défaut est d'une minute.

Il est important de noter que vous spécifiez des 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 et le produit B peut avoir un intervalle de quota de 10 000 requêtes par heure.

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

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

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

En gardant ces paramètres de quota à l'esprit, comment le plug-in quota Edge Microgateway doit-il être configuré ? Une bonne pratique consiste à configurer Edge Microgateway avec des intervalles de synchronisation inférieurs à ceux 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 de "minutes". Edge Microgateway se synchronise avec Edge toutes les 50 requêtes ou toutes les 5 secondes, selon la première échéance atteinte.
• Le produit B est défini sur l'intervalle "heure". Edge Microgateway se synchronisera avec Edge toutes les 2 000 requêtes ou une minute, selon la première échéance atteinte.
• Le produit C est défini sur l'intervalle "mois". Edge Microgateway se synchronise avec Edge après chaque requête ou une minute, selon la première échéance atteinte.

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

Les paramètres bufferSize vous permettent d'ajuster la synchronisation du compteur de quota avec Edge. En cas de trafic élevé, les paramètres bufferSize permettent au compteur de tampon de se synchroniser avant le déclenchement de la synchronisation temporelle par défaut.

Comprendre le champ d'application des quotas

Le quota est limité à un environnement dans une organisation. Pour atteindre ce champ d'application, Edge Microgateway crée un identifiant de quota combinant "org + env + appName + productName".

Utiliser un magasin de sauvegarde Redis pour le quota

Pour utiliser un magasin de sauvegarde Redis pour le quota, utilisez la même configuration que celle de la fonctionnalité de synchronisateur. 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, avec 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 le bon outil pour 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 en une heure, une journée, une semaine ou un mois. La règle de quotas permet d'appliquer des limites de consommation aux applications clientes en maintenant un compteur distribué qui comptabilise les requêtes entrantes.

Utilisez des règles de quotas pour faire respecter des contrats commerciaux ou des contrats de niveau de service avec les développeurs et les partenaires, plutôt que pour gérer le trafic opérationnel. Par exemple, un quota peut être utilisé pour limiter le trafic d'un service sans frais, tout en permettant un accès complet aux clients payants.

Utilisez l'arrêt des pics pour vous protéger contre les pics soudains de trafic des API. L'arrêt des pics est généralement utilisé pour écarter d'éventuelles attaques DDoS ou d'autres attaques malveillantes.