Documentation de référence sur le fonctionnement et la configuration d'Edge Microgateway

Vous consultez la documentation sur Apigee Edge.
Consultez la documentation sur Apigee X.

Edge Microgateway version 3.1.x

Cet article explique comment gérer et configurer Edge Microgateway.

Mettre à niveau Edge Microgateway si vous disposez d'une connexion Internet

Cette section explique comment mettre à niveau une installation Edge Microgateway existante. Si vous utilisez une connexion sans connexion Internet, consultez la section Puis-je installer Edge Microgateway sans connexion Internet ?.

Apigee vous recommande de tester votre configuration existante avec la nouvelle version avant de mettre à niveau votre environnement de production.

1. Exécutez la commande npm suivante pour passer à la dernière version d'Edge Microgateway :

   npm upgrade edgemicro -g

   Pour effectuer la mise à niveau vers une version spécifique d'Edge Microgateway, vous devez spécifier le numéro de version dans la commande de mise à niveau. Si vous n'indiquez pas le numéro de version, la dernière version sera installée. Par exemple, pour passer à la version 3.1.0, utilisez la commande suivante:

   npm upgrade edgemicro@3.1.0 -g

2. Vérifiez le numéro de version. Par exemple, si vous avez installé la version 3.1.0 :

   edgemicro --version
   current nodejs version is v12.5.0
   current edgemicro version is 3.1.0
       

3. Enfin, installez la dernière version du proxy edgemicro-auth :

   edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME

Apporter des modifications à la configuration

Voici les fichiers de configuration à connaître:

• Fichier de configuration système par défaut
• Fichier de configuration par défaut pour une instance Edge Microgateway récemment initialisée
• Fichier de configuration dynamique pour les instances en cours d'exécution

Cette section traite de ces fichiers et de ce que vous devez savoir pour les modifier.

Fichier de configuration système par défaut

Lorsque vous installez Edge Microgateway, un fichier de configuration système par défaut est placé ici:

prefix/lib/node_modules/edgemicro/config/default.yaml

Où prefix correspond au répertoire de préfixes npm. Si vous ne parvenez pas à trouver ce répertoire, consultez Où est installé Edge Microgateway.

Si vous modifiez le fichier de configuration système, vous devez réinitialiser, reconfigurer et redémarrer Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

Fichier de configuration par défaut pour les instances Edge Microgateway récemment initialisées

Lorsque vous exécutez edgemicro init, le fichier de configuration système (décrit ci-dessus), default.yaml, est placé dans le répertoire ~/.edgemicro.

Si vous modifiez le fichier de configuration dans ~/.edgemicro, vous devez reconfigurer et redémarrer Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

Fichier de configuration dynamique pour les instances en cours d'exécution

Lorsque vous exécutez edgemicro configure [params], un fichier de configuration dynamique est créé dans ~/.edgemicro. Le fichier est nommé selon ce format: org-env-config.yaml, où org et env correspondent aux noms de votre organisation et de votre environnement Apigee Edge. Vous pouvez utiliser ce fichier pour modifier la configuration, puis actualiser la page sans temps d'arrêt. Par exemple, si vous ajoutez et configurez un plug-in, vous pouvez actualiser la configuration sans entraîner de temps d'arrêt, comme expliqué ci-dessous.

Si Edge Microgateway est en cours d'exécution (option sans aucun temps d'arrêt):

1. Actualisez la configuration Edge Microgateway :

   edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET

   Où :

   • $ORG est le nom de votre organisation Edge (vous devez être un administrateur de l'organisation).
   • $ENV est un environnement de votre organisation (par exemple, "test" ou "prod").
   • $KEY est la clé renvoyée précédemment par la commande "configure".
   • $SECRET est la clé renvoyée précédemment par la commande "configure".

   Exemple

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

Si Edge Microgateway est arrêté:

1. Redémarrez Edge Microgateway :

   edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Où :

   • $ORG est le nom de votre organisation Edge (vous devez être un administrateur de l'organisation).
   • $ENV est un environnement de votre organisation (par exemple, "test" ou "prod").
   • $KEY est la clé renvoyée précédemment par la commande "configure".
   • $SECRET est la clé renvoyée précédemment par la commande "configure".

   Exemple :

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Voici un exemple de fichier de configuration. Pour en savoir plus sur les paramètres de fichier de configuration, consultez la documentation de référence sur la configuration d'Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Définir des variables d'environnement

Les commandes d'interface de ligne de commande qui nécessitent des valeurs pour votre organisation et votre environnement Edge, ainsi que la clé et le code secret nécessaires au démarrage d'Edge Microgateway peuvent être stockés dans les variables d'environnement suivantes:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

La définition de ces variables est facultative. Si vous les définissez, vous n'avez pas besoin de spécifier leurs valeurs lorsque vous utilisez l'interface de ligne de commande (CLI) pour configurer et démarrer Edge Microgateway.

Configurer SSL sur le serveur Edge Microgateway

Regardez les vidéos suivantes pour en savoir plus sur la configuration de TLS dans Apigee Edge Microgateway:

Vidéo	Description
Configurer le TLS TLS à sens unique	Découvrez comment configurer le protocole TLS dans Apigee Edge Microgateway. Cette vidéo présente le protocole TLS et son importance. Il présente également le protocole TLS dans Edge Microgateway et montre comment configurer le protocole TLS unidirectionnel.
Configurer la norme TLS bidirectionnelle	Il s'agit de la deuxième vidéo sur la configuration de TLS dans Apigee Edge Microgateway. Cette vidéo vous explique comment configurer le protocole TLS bidirectionnel vers le nord.
Configurer un TLS bidirectionnel	Cette troisième vidéo explique comment configurer le protocole TLS unidirectionnel et bidirectionnel d'Apigee Edge.

Vous pouvez configurer le serveur Microgateway pour utiliser SSL. Par exemple, avec SSL configuré, vous pouvez appeler des API via Edge Microgateway avec le protocole "https", comme suit:

https://localhost:8000/myapi

Pour configurer SSL sur le serveur Microgateway, procédez comme suit:

1. Générez ou obtenez un certificat et une clé SSL à l'aide de l'utilitaire openssl ou de la méthode de votre choix.
2. Ajoutez l'attribut edgemicro:ssl au fichier de configuration Edge Microgateway. Pour obtenir la liste complète des options, consultez le tableau ci-dessous. Par exemple:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Redémarrez Edge Microgateway. Suivez la procédure décrite dans la section Apporter des modifications à la configuration en fonction du fichier de configuration que vous avez modifié: le fichier par défaut ou le fichier de configuration d'exécution.

Voici un exemple de la section edgemicro du fichier de configuration, avec SSL configuré:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Voici la liste des options de serveur disponibles:

Option	Description
key	Chemin d'accès à un fichier ca.key (au format PEM).
cert	Chemin d'accès à un fichier ca.cert (au format PEM).
pfx	Chemin d'accès à un fichier pfx contenant la clé privée, le certificat et les certificats CA du client au format PFX.
passphrase	Chaîne contenant la phrase secrète de la clé privée ou PFX.
ca	Chemin d'accès à un fichier contenant une liste de certificats approuvés au format PEM.
ciphers	Chaîne décrivant les algorithmes de chiffrement à utiliser, séparée par un caractère ":".
rejectUnauthorized	Si la valeur est "true", le certificat de serveur est validé par rapport à la liste des autorités de certification fournies. Si la validation échoue, une erreur est renvoyée.
secureProtocol	Méthode SSL à utiliser. Par exemple, SSLv3_method permet de forcer le chiffrement SSL vers la version 3.
servername	Nom du serveur de l'extension TLS (Server Name Indication).
requestCert	"true" pour la norme SSL à double sens, "false" pour la norme SSL à double sens

Utiliser les options SSL/TLS du client

Vous pouvez configurer Edge Microgateway en tant que client TLS ou SSL lorsque vous vous connectez aux points de terminaison cibles. Dans le fichier de configuration Microgateway, définissez les options SSL/TLS avec l'élément cible.

Cet exemple fournit des paramètres qui seront appliqués à tous les hôtes:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

Dans cet exemple, les paramètres ne sont appliqués qu'à l'hôte spécifié:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Voici un exemple de protocole TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Voici la liste de toutes les options disponibles pour le client:

Option	Description
pfx	Chemin d'accès à un fichier pfx contenant la clé privée, le certificat et les certificats CA du client au format PFX.
key	Chemin d'accès à un fichier ca.key (au format PEM).
passphrase	Chaîne contenant la phrase secrète de la clé privée ou PFX.
cert	Chemin d'accès à un fichier ca.cert (au format PEM).
ca	Chemin d'accès à un fichier contenant une liste de certificats approuvés au format PEM.
ciphers	Chaîne décrivant les algorithmes de chiffrement à utiliser, séparée par un caractère ":".
rejectUnauthorized	Si la valeur est "true", le certificat de serveur est validé par rapport à la liste des autorités de certification fournies. Si la validation échoue, une erreur est renvoyée.
secureProtocol	Méthode SSL à utiliser. Par exemple, SSLv3_method permet de forcer le chiffrement SSL vers la version 3.
servername	Nom du serveur de l'extension TLS (Server Name Indication).

Personnaliser le proxy périphérique

Par défaut, Edge Microgateway utilise un proxy déployé sur Apigee Edge pour l'authentification OAuth2. Ce proxy est déployé lorsque vous exécutez initialement edgemicro configure. Vous pouvez modifier la configuration par défaut de ce proxy afin de prendre en charge les revendications personnalisées avec un jeton Web JSON (JWT), de configurer l'expiration du jeton et de générer des jetons d'actualisation. Pour en savoir plus, consultez la page edgemicro-auth sur GitHub.

Utiliser un service d'authentification personnalisé

Par défaut, Edge Microgateway utilise un proxy déployé sur Apigee Edge pour l'authentification OAuth2. Ce proxy est déployé lorsque vous exécutez initialement edgemicro configure. Par défaut, l'URL de ce proxy est spécifiée dans le fichier de configuration Edge Microgateway comme suit:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Si vous souhaitez utiliser votre propre service personnalisé pour gérer l'authentification, modifiez la valeur authUri du fichier de configuration pour qu'elle pointe vers votre service. Par exemple, un service peut utiliser LDAP pour valider l'identité.

Gérer les fichiers journaux

Edge Microgateway fournit des informations sur chaque requête et chaque réponse. Les fichiers journaux fournissent des informations utiles pour le débogage et le dépannage.

Emplacement de stockage des fichiers journaux

Par défaut, les fichiers journaux sont stockés dans /var/tmp.

Modifier le répertoire de fichiers journaux par défaut

Le répertoire dans lequel les fichiers journaux sont stockés est spécifié dans le fichier de configuration Edge Microgateway. Consultez également la section Modifier la configuration.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Modifiez la valeur dir pour spécifier un autre répertoire de fichiers journaux.

Envoyer les journaux à la console

Vous pouvez configurer la journalisation de sorte que les informations de journal soient envoyées à la sortie standard plutôt qu'à un fichier journal. Définissez l'indicateur to_console sur "true" comme suit:

edgemicro:
  logging:
    to_console: true

Avec ce paramètre, les journaux sont envoyés à la sortie standard. Actuellement, vous ne pouvez pas envoyer de journaux à stdout ni à un fichier journal.

Définir le niveau de journalisation

Vous pouvez définir les niveaux de journalisation suivants: info, warn et error. Le niveau d'information est recommandé. Il enregistre toutes les requêtes et réponses de l'API. Il s'agit de la valeur par défaut.

Modifier les intervalles de journaux

Vous pouvez configurer ces intervalles dans le fichier de configuration Edge Microgateway. Consultez également Modifier la configuration.

Les attributs configurables sont les suivants:

• stats_log_interval: (par défaut: 60) intervalle, en secondes, lorsque l'enregistrement des statistiques est écrit dans le fichier journal de l'API.
• rotate_interval: (par défaut: 24) intervalle, en heures, lors de la rotation des fichiers journaux. Exemple :

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Bonnes pratiques de maintenance pour les fichiers journaux

À mesure que les données du fichier journal s'accumulent, Apigee vous recommande d'adopter les pratiques suivantes:

• Étant donné que les fichiers journaux peuvent devenir assez volumineux, assurez-vous que l'espace disponible dans le répertoire de fichiers journaux est suffisant. Consultez les sections suivantes : Emplacement de stockage des fichiers journaux et Comment modifier le répertoire de fichiers journaux par défaut.
• Supprimez ou déplacez des fichiers journaux dans un répertoire d'archives séparé au moins une fois par semaine.
• Si votre règle consiste à supprimer des journaux, vous pouvez utiliser la commande CLI edgemicro log -c pour les supprimer (nettoyer).

Convention d'attribution de noms aux fichiers journaux

Chaque instance Edge Microgateway produit trois types de fichiers journaux:

• api - Consigne toutes les requêtes et réponses qui transitent par Edge Microgateway. Les compteurs d'API (statistiques) et les erreurs sont également enregistrés dans ce fichier.
• err : consigne tout ce qui est envoyé à stderr.
• out : consigne tous les éléments envoyés à stdout.

Voici la convention d'attribution de noms:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Exemple :

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

À propos du contenu des fichiers journaux

Ajoutée dans la version 2.3.3

Par défaut, le service de journalisation omet le JSON des proxys, produits et jeton Web JSON (JWT) téléchargés. Si vous souhaitez générer ces objets dans les fichiers journaux, définissez DEBUG=* lorsque vous démarrez Edge Microgateway. Exemple :

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Contenu du fichier journal "api"

Le fichier journal "api" contient des informations détaillées sur le flux des requêtes et des réponses via Edge Microgateway. Les fichiers journaux "api" sont nommés comme suit:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Pour chaque requête envoyée à Edge Microgateway, quatre événements sont capturés dans le fichier journal "api" :

• Requête entrante du client
• Requête sortante envoyée à la cible
• Réponse entrante de la cible
• Réponse sortante au client

Chacune de ces entrées distinctes est représentée par une notation abrégée afin de rendre les fichiers journaux plus compacts. Voici quatre exemples d'entrées représentant chacun des quatre événements. Ils se présentent comme suit (dans le fichier journal, les numéros de ligne ne sont fournis qu'à titre de référence ; ils n'apparaissent pas dans le fichier journal).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Examinons-les une par une:

1. Exemple de requête entrante du client:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651 : horodatage Unix
• info : dépend du contexte. Il peut s'agir d'informations, d'avertissements ou d'erreurs, en fonction du niveau de journalisation. Il peut s'agir de statistiques pour un enregistrement de statistiques, d'un avertissement pour les avertissements ou d'une erreur pour les erreurs.
• req : identifie l'événement. Dans ce cas, effectuez la requête auprès du client.
• m : verbe HTTP utilisé dans la requête
• u – Partie de l'URL qui suit le chemin de base.
• h : hôte et numéro de port sur lesquels Edge Microgateway écoute.
• r : hôte et port distant d'origine de la requête client.
• i : ID de la requête. Les quatre entrées d'événement partagent cet ID. Un ID unique est attribué à chaque requête. La mise en corrélation des enregistrements de journaux par ID de requête peut fournir des informations précieuses sur la latence de la cible.
• d : durée, en millisecondes, pendant laquelle la requête a été reçue par Edge Microgateway. Dans l'exemple ci-dessus, la réponse de la cible 0 a été reçue après 7 millisecondes (ligne 3), et la réponse a été envoyée au client au bout de 4 millisecondes (ligne 4). En d'autres termes, la latence totale de la requête était de 11 millisecondes, dont 7 millisecondes ont été prises par la cible et 4 millisecondes par Edge Microgateway lui-même.

2. Exemple de requête sortante envoyée à la cible:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651 : horodatage Unix
• info : dépend du contexte. Il peut s'agir d'informations, d'avertissements ou d'erreurs, en fonction du niveau de journalisation. Il peut s'agir de statistiques pour un enregistrement de statistiques, d'un avertissement pour les avertissements ou d'une erreur pour les erreurs.
• treq : identifie l'événement. Dans ce cas, "target request".
• m : verbe HTTP utilisé dans la requête cible
• u – Partie de l'URL qui suit le chemin de base.
• h : hôte et numéro de port de la cible du backend.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partagent cet ID.

3. Exemple de réponse entrante de la cible

1436403888672 info tres s=200, d=7, i=0

1436403888651 : horodatage Unix

• info : dépend du contexte. Il peut s'agir d'informations, d'avertissements ou d'erreurs, en fonction du niveau de journalisation. Il peut s'agir de statistiques pour un enregistrement de statistiques, d'un avertissement pour les avertissements ou d'une erreur pour les erreurs.
• tres : identifie l'événement. Dans ce cas, ciblez la réponse.
• s : état de la réponse HTTP.
• d : durée, en millisecondes. Temps nécessaire à l'appel d'API par la cible.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partagent cet ID.

4. Exemple de réponse sortante au client

1436403888676 info res s=200, d=11, i=0

1436403888651 : horodatage Unix

• info : dépend du contexte. Il peut s'agir d'informations, d'avertissements ou d'erreurs, en fonction du niveau de journalisation. Il peut s'agir de statistiques pour un enregistrement de statistiques, d'un avertissement pour les avertissements ou d'une erreur pour les erreurs.
• res : identifie l'événement. Dans ce cas, réponse au client.
• s : état de la réponse HTTP.
• d : durée, en millisecondes. Il s'agit du temps total pris par l'appel d'API, y compris le temps pris par l'API cible et le temps pris par Edge Micromicro en lui-même.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partagent cet ID.

Planification des fichiers journaux

Les fichiers journaux sont alternés à l'intervalle spécifié par l'attribut de configuration rotate_interval. Les entrées continueront d'être ajoutées au même fichier journal jusqu'à l'expiration de l'intervalle de rotation. Cependant, chaque fois qu'Edge Microgateway est redémarré, il reçoit un nouvel UID et crée un ensemble de fichiers journaux avec cet UID. Consultez également les bonnes pratiques de maintenance des fichiers journaux.

Messages d'erreur

Certaines entrées de journal contiennent des messages d'erreur. Pour savoir où et pourquoi les erreurs se produisent, consultez la documentation de référence sur les erreurs Edge Microgateway.

Documentation de référence sur la configuration d'Edge Microgateway

Emplacement du fichier de configuration

Les attributs de configuration décrits dans cette section se trouvent dans le fichier de configuration Edge Microgateway. Consultez également la section Modifier la configuration.

Attributs Edge_config

Ces paramètres permettent de configurer l'interaction entre l'instance Edge Microgateway et Apigee Edge.

• bootstrap: (par défaut: aucun) une URL qui pointe vers un service spécifique à Edge Microgateway exécuté sur Apigee Edge. Edge Microgateway utilise ce service pour communiquer avec Apigee Edge. Cette URL est renvoyée lorsque vous exécutez la commande pour générer la paire de clés publique/privée: edgemicro genkeys. Pour en savoir plus, consultez la page Configurer et configurer Edge Microgateway.
• jwt_public_key: (par défaut: aucun) une URL qui pointe vers le proxy Edge Microgateway déployé sur Apigee Edge. Ce proxy sert de point de terminaison d'authentification pour émettre des jetons d'accès signés aux clients. Cette URL est renvoyée lorsque vous exécutez la commande suivante pour déployer le proxy: edgemicro configure. Pour en savoir plus, consultez la page Configurer et configurer Edge Microgateway.
• quotaUri: définissez cette propriété de configuration si vous souhaitez gérer les quotas via le proxy edgemicro-auth déployé sur votre organisation. Si cette propriété n'est pas définie, le point de terminaison du quota est défini par défaut sur le point de terminaison interne Edge Microgateway.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

Attributs Edgemicro

Ces paramètres configurent le processus Edge Microgateway.

• port: (par défaut: 8000) Numéro de port sur lequel le processus Edge Microgateway écoute.
• max_connections: (par défaut: -1) spécifie le nombre maximal de connexions entrantes simultanées que Edge Microgateway peut recevoir. Si ce nombre est dépassé, l'état suivant est renvoyé:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard (valeur par défaut : -1) : nombre maximal de requêtes simultanées que Edge Microgateway peut recevoir avant l'arrêt de la connexion. Ce paramètre est conçu pour contrecarrer les attaques par déni de service. Généralement, définissez-le sur un nombre supérieur à max_connections.
• logging:
  • level: (par défaut: erreur)
    • info : consigne toutes les requêtes et réponses qui transitent par une instance Edge Microgateway.
    • warn : consigne uniquement les messages d'avertissement.
    • error : consigne uniquement les messages d'erreur.
  • dir: (par défaut: /var/tmp) répertoire dans lequel les fichiers journaux sont stockés.
  • stats_log_interval: (par défaut: 60) intervalle, en secondes, lorsque l'enregistrement des statistiques est écrit dans le fichier journal de l'API.
  • rotate_interval: (par défaut: 24) intervalle, en heures, lors de la rotation des fichiers journaux.

• plug-ins: les plug-ins ajoutent des fonctionnalités à Edge Microgateway. Pour en savoir plus sur le développement de plug-ins, consultez Développer des plug-ins personnalisés.

• dir: chemin d'accès relatif du répertoire ./gateway vers le répertoire ./plugins, ou chemin d'accès absolu.
• sequence: liste des modules de plug-ins à ajouter à votre instance Edge Microgateway. Les modules s'exécutent dans l'ordre dans lequel ils sont spécifiés.

• debug : ajoute un débogage à distance au processus Edge Microgateway.
  • port: numéro de port sur lequel écouter. Par exemple, définissez votre débogueur IDE pour écouter sur ce port.
  • args: arguments du processus de débogage. Exemple :args --nolazy
    
• config_change_poll_interval : (valeur par défaut: 600 secondes) Edge Microgateway charge régulièrement une nouvelle configuration et exécute une actualisation en cas de changement. L'interrogation détecte toutes les modifications apportées sur Edge (modifications des produits, proxys prenant en charge la micropasserelle, etc.), ainsi que les modifications apportées au fichier de configuration local.
  
• disable_config_poll_interval : (valeur par défaut: false) défini sur true pour désactiver l'interrogation automatique des modifications.
• request_timeout: définit un délai avant expiration pour les requêtes cibles. Le délai avant expiration est défini en secondes. En cas d'expiration du délai, Edge Microgateway renvoie un code d'état 504. (Version 2.4.x ajoutée)
• keep_alive_timeout: cette propriété vous permet de définir le délai avant expiration de la micropasserelle périphérique (en millisecondes). (Valeur par défaut: 5 secondes) (version 3.0.6 ajoutée)
• headers_timeout: cet attribut limite la durée (en millisecondes) pendant laquelle l'analyseur HTTP attend de recevoir les en-têtes HTTP complets.

  Exemple :

  edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000

  En interne, le paramètre définit l'attribut Server.headersTimeout de Node.js sur les requêtes. (Par défaut: 5 secondes de plus que le temps défini avec edgemicro.keep_alive_timeout. Ce paramètre par défaut empêche les équilibreurs de charge ou les proxys de supprimer la connexion par erreur.) (Version 3.1.1 ajoutée)

attributs de titre

Ces paramètres configurent le traitement de certains en-têtes HTTP.

• x-forwarded-for: (par défaut: true) défini sur "false" pour empêcher la transmission d'en-têtes x-forwarded-for à la cible. Notez que si un en-tête x-Forwarded-for se trouve dans la requête, sa valeur sera définie sur la valeur client-ip dans Edge Analytics.
• x-forwarded-host: (par défaut: true) défini sur "false" pour empêcher la transmission d'en-têtes x-forwarded-host à la cible
• x-request-id: (par défaut: true) défini sur "false" pour empêcher la transmission des en-têtes x-request-id à la cible.
• x-response-time: (par défaut: true) défini sur "false" pour empêcher la transmission des en-têtes x-response-time.
• via (valeur par défaut : true) défini sur "false" pour empêcher la transmission des en-têtes à la cible

Attributs OAuth

Ces paramètres configurent la manière dont l'authentification client est appliquée par Edge Microgateway.

• allowNoAuthorization: (valeur par défaut: false) si la valeur est définie sur "true", les appels d'API peuvent passer par Edge Microgateway sans en-tête Authorization. Définissez cette valeur sur "false" pour exiger un en-tête Authorization (par défaut).
• allowInvalidAuthorization: (valeur par défaut: false) si la valeur est définie sur "true", les appels d'API peuvent être transmis si le jeton transmis dans l'en-tête Authorization est incorrect ou expiré. Définissez ce paramètre sur "false" pour exiger des jetons valides (par défaut).
• authorization-header: (par défaut: Authorization: Bearer) L'en-tête utilisé pour envoyer le jeton d'accès à Edge Microgateway Vous pouvez modifier la valeur par défaut si la cible doit utiliser l'en-tête Authorization à d'autres fins.
• api-key-header: (par défaut: x-api-key) nom de l'en-tête ou du paramètre de requête utilisé pour transmettre une clé API à Edge Microgateway Consultez également la section Utiliser une clé API.
• keep-authorization-header: (default: false) Si la valeur est définie sur "true", l'en-tête Authorization envoyé dans la requête est transmis à la cible (il est conservé).
• allowOAuthOnly : si ce champ est défini sur "true", chaque API doit comporter un en-tête Authorization avec un jeton d'accès au support. Vous permet de n'autoriser que le modèle de sécurité OAuth (tout en conservant la rétrocompatibilité). (Ajoutée 2.4.x)
• allowAPIKeyOnly : si elle est définie sur "true", chaque API doit comporter un en-tête x-api-key (ou un emplacement personnalisé) avec une clé API.Vous ne pouvez autoriser que le modèle de sécurité de la clé API (tout en conservant la rétrocompatibilité). (Ajouté à la version 2.4.x)
• gracePeriod : ce paramètre permet d'éviter les erreurs causées par de légers écarts entre votre horloge système et les heures "Pas avant" (nbf) ou "Émis à" (iat) spécifiées dans le jeton d'autorisation du jeton JWT. Définissez ce paramètre sur le nombre de secondes autorisé pour de tels écarts. (ajout de la version 2.5.7)

Attributs spécifiques du plug-in

Pour en savoir plus sur les attributs configurables de chaque plug-in, consultez "Utiliser des plug-ins".

Filtrer les proxys

Vous pouvez filtrer les proxys compatibles avec la micropasserelle qu'une instance Edge Microgateway va traiter. Au démarrage d'Edge Microgateway, tous les proxys compatibles de la passerelle qui sont associés dans l'organisation à laquelle il est associé sont téléchargés. Utilisez la configuration suivante pour limiter les proxys traités par la micropasserelle. Par exemple, cette configuration limite les proxys que la micropassera traitera à trois: edgemicro_proxy-1, edgemicro_proxy-2 et edgemicro_proxy-3:

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Filtrer les produits

Utilisez la configuration suivante pour limiter le nombre de produits d'API téléchargés et traités par Edge Microgateway. Pour filtrer les produits téléchargés, ajoutez le paramètre de requête productnamefilter à l'API /products répertoriée dans le fichier Edge Microgateway *.config.yaml. Exemple :

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Notez que la valeur du paramètre de requête doit être spécifiée au format d'expression régulière et doit être encodée au format URL. Par exemple, l'expression régulière ^[Ee]dgemicro.*$ détecte des noms tels que : "edgemicro-test-1" , "edgemicro_demo" et "Edgemicro_New_Demo". La valeur encodée au format URL, qui peut être utilisée dans le paramètre de requête, est la suivante: %5E%5BEe%5Ddgemicro.%2A%24.

La sortie de débogage suivante montre que seuls les produits filtrés ont été téléchargés:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Configuration de la fréquence d'envoi des données analytiques

Utilisez ces paramètres de configuration pour contrôler la fréquence à laquelle Edge Microgateway envoie des données d'analyse à Apigee:

• bufferSize (facultatif): nombre maximal d'enregistrements d'analyse que le tampon peut contenir avant de commencer à supprimer les enregistrements les plus anciens. Valeur par défaut: 10 000
• batchSize (facultatif): taille maximale d'un lot d'enregistrements d'analyse envoyés à Apigee. Valeur par défaut: 500
• flushInterval (facultatif): nombre de millisecondes entre chaque vidage d'un lot d'enregistrements d'analyse envoyés à Apigee. Valeur par défaut: 5 000

Exemple :

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Masquage des données d'analyse

La configuration suivante empêche l'affichage des informations de chemin de requête dans l'analyse périphérique. Ajoutez le code suivant à la configuration de la passerelle micro afin de masquer l'URI et/ou le chemin d'accès de la requête. Notez que l'URI se compose des noms d'hôte et de chemin d'accès de la requête.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Séparer les appels d'API dans Edge Analytics

Vous pouvez configurer le plug-in d'analyse pour séparer un chemin d'accès d'API spécifique afin qu'il apparaisse comme un proxy distinct dans les tableaux de bord Edge Analytics. Par exemple, vous pouvez séparer une API de vérification d'état dans le tableau de bord afin d'éviter toute confusion avec les appels de proxy d'API réels. Dans le tableau de bord Analytics, les proxys séparés suivent le modèle de dénomination suivant:

edgemicro_proxyname-health

L'image suivante montre deux proxys séparés dans le tableau de bord Analytics: edgemicro_hello-health et edgemicro_mock-health:

Utilisez ces paramètres pour séparer les chemins d'accès relatifs et absolus dans le tableau de bord Analytics en tant que proxys distincts:

• relativePath (facultatif): indique un chemin d'accès relatif à séparer dans le tableau de bord Analytics. Par exemple, si vous spécifiez /healthcheck, tous les appels d'API contenant le chemin /healthcheck apparaissent dans le tableau de bord en tant que edgemicro_proxyname-health. Notez que cet indicateur ignore le chemin de base du proxy. Pour séparer en fonction d'un chemin d'accès complet, y compris du chemin de base, utilisez l'indicateur proxyPath.
• proxyPath (facultatif): spécifie un chemin de proxy d'API complet, y compris le chemin de base du proxy, à séparer dans le tableau de bord d'analyse. Par exemple, si vous spécifiez /mocktarget/healthcheck, où /mocktarget est le chemin de base du proxy, tous les appels d'API portant le chemin /mocktarget/healthcheck apparaîtront dans le tableau de bord en tant que edgemicro_proxyname-health.

Par exemple, dans la configuration suivante, tout chemin d'API contenant /healthcheck sera séparé par le plug-in d'analyse. Cela signifie que /foo/healthcheck et /foo/bar/healthcheck seront séparés en tant que proxy distinct appelé edgemicro_proxyname-health dans le tableau de bord d'analyse.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Dans la configuration suivante, toute API ayant le chemin de proxy /mocktarget/healthcheck sera distincte dans le tableau de bord d'analyse en tant que proxy distinct appelé edgemicro_proxyname-health.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Configuration d'Edge Microgateway derrière un pare-feu d'entreprise

Utiliser un proxy HTTP pour communiquer avec Apigee Edge

Ajouté dans la version 3.1.2.

Pour utiliser un proxy HTTP pour la communication entre Edge Microgateway et Apigee Edge, procédez comme suit:

1. Définissez les variables d'environnement HTTP_PROXY, HTTPS_PROXY et NO_PROXY. Ces variables contrôlent les hôtes de chaque proxy HTTP que vous souhaitez utiliser pour communiquer avec Apigee Edge, ou ceux qui ne doivent pas gérer la communication avec Apigee Edge. Exemple :

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   Notez que NO_PROXY peut être une liste de domaines séparés par une virgule auxquels Edge Microgateway ne doit pas être associé par un proxy.

   Pour en savoir plus sur ces variables, consultez la page https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

2. Redémarrez Edge Microgateway.

Utiliser un proxy HTTP pour la communication cible

Ajouté dans la version 3.1.2.

Pour utiliser un proxy HTTP pour la communication entre Edge Microgateway et les cibles de backend, procédez comme suit:

1. Ajoutez la configuration suivante au fichier de configuration de la passerelle :

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   Où :

   • tunnel (facultatif) : si la valeur est "true", Edge Microgateway utilise la méthode HTTP CONNECT pour canaliser les requêtes HTTP via une seule connexion TCP. Il en va de même si les variables d'environnement, comme indiqué ci-dessous, permettent de configurer le proxy et d'activer le protocole TLS. Par défaut : false
   • url: URL du proxy HTTP.
   • bypass (facultatif) : spécifie une ou plusieurs URL hôtes cibles séparées par une virgule qui doivent contourner le proxy HTTP. Si cette propriété n'est pas définie, utilisez la variable d'environnement NO_PROXY pour spécifier les URL cibles à ignorer.
   • enabled: si "true" et proxy.url est défini, utilisez la valeur proxy.url pour le proxy HTTP. Si "true" et proxy.url n'est pas défini, utilisez les proxys spécifiés dans les variables d'environnement de proxy HTTP HTTP_PROXY et HTTPS_PROXY, comme décrit dans la section Utiliser un proxy HTTP pour communiquer avec Apigee Edge.

   Par exemple :

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. Redémarrez Edge Microgateway.

Utiliser les caractères génériques dans les proxys compatibles avec Microgateway

Vous pouvez utiliser un ou plusieurs caractères génériques "*" dans le chemin de base d'un proxy edgemicro_* (compatible avec la passerelle Micro). Par exemple, le chemin de base /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans avoir à créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.

Important:Apigee ne permet PAS d'utiliser le caractère générique "*" comme premier élément d'un chemin de base. Par exemple, cela n'est PAS compatible avec la recherche /*/.

Effectuer une rotation des clés JWT

Quelque temps après avoir généré un JWT, vous devrez peut-être modifier la paire de clés publique/privée stockée dans la KVM chiffrée en périphérie. Ce processus de génération d'une nouvelle paire de clés est appelé "rotation des clés".

Comment Edge Microgateway utilise le jeton JWT

Le jeton Web JSON (JWT, JSON Web Token) est une norme de jeton décrite dans la RFC7519. Un jeton JWT permet de signer un ensemble de revendications, qui peuvent être validées de manière fiable par le destinataire du jeton JWT.

Edge Microgateway utilise les JWT comme jetons de support pour la sécurité OAuth. Lorsque vous générez un jeton OAuth pour Edge Microgateway, vous recevez un jeton JWT. Vous pouvez ensuite utiliser le jeton JWT dans l'en-tête Authorization des appels d'API. Exemple :

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Générer un nouveau jeton JWT

Vous pouvez générer un jeton JWT pour Edge Microgateway à l'aide de la commande edgemicro token ou d'une API. Exemple :

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Cette commande demande à Apigee Edge de générer un jeton JWT qui peut ensuite être utilisé pour vérifier les appels d'API. Les paramètres -i et -s sont l'ID client et les valeurs secrètes d'une application de développement dans votre organisation Apigee Edge.

Vous pouvez également générer un jeton JWT à l'aide de l'API de gestion:

curl -i -X POST "http://$ORG-$ENV.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "$CLIENT_ID": "your consumer key",
    "$CLIENT_SECRET": "your consumer secret",
    "grant_type": "client_credentials"
  }'

Où :

• $ORG est le nom de votre organisation Edge (vous devez être administrateur de l'organisation).
• $ENV est un environnement de votre organisation (par exemple, "test" ou "prod").
• $CLIENT_ID est l'ID client que vous avez créé précédemment dans l'application pour les développeurs.
• $CLIENT_SECRET est le code secret client dans l'application de développement que vous avez créée précédemment.

Qu'est-ce que la rotation des clés ?

Quelque temps après avoir généré un JWT, vous devrez peut-être modifier la paire de clés publique/privée stockée dans la KVM chiffrée en périphérie. Ce processus de génération d'une nouvelle paire de clés est appelé "rotation des clés". Lorsque vous effectuez une rotation de clés, une nouvelle paire de clés publique/privée est générée et stockée dans la KVM "microgateway" de votre organisation/environnement Apigee Edge. De plus, l'ancienne clé publique est conservée avec sa valeur d'ID de clé d'origine.

Pour générer un JWT, Edge utilise les informations stockées dans la KVM chiffrée. Une VM KVM appelée microgateway a été créée et a été renseignée avec des clés lors de la configuration initiale (en configuration) d'Edge Microgateway. Les clés dans la KVM permettent de signer et de chiffrer un jeton JWT.

Les clés KVM incluent:

• private_key : la clé privée RSA la plus récente (créée récemment) utilisée pour signer des jetons JWT.

• public_key : certificat le plus récent (le plus récemment créé) utilisé pour valider les jetons JWT signés avec l'élément private_key.

• private_key_kid : ID de la clé privée la plus récente (la plus récemment créée). Cet ID de clé est associé à la valeur "private_key" et permet de faire pivoter les clés.

• public_key1_kid : l'ID de clé publique le plus récent (le plus récent). Cette clé est associée à la valeur "public_key1" et est utilisée pour la rotation des clés. Cette valeur est identique à celle de l'enfant de la clé privée.

• public_key1 : la dernière clé publique (la plus récente).

Lorsque vous effectuez une rotation des clés, les valeurs existantes sont remplacées dans le mappage et de nouvelles clés sont ajoutées afin de conserver les anciennes clés publiques. Exemple :

• public_key2_kid : ancien ID de clé publique. Cette clé est associée à la valeur "public_key2" et est utilisée pour la rotation des clés.

• public_key2 : ancienne clé publique.

Les jetons JWT présentés pour la validation seront validés à l'aide de la nouvelle clé publique. Si la validation échoue, l'ancienne clé publique est utilisée jusqu'à son expiration (au bout de 30 minutes). De cette façon, vous pouvez effectuer une "rotation" des clés sans perturber le trafic des API.

Effectuer une rotation des clés

Cette section explique comment effectuer une rotation des clés.

Si vous avez configuré votre instance Edge Microgateway avant la version 2.5.2

Si vous avez configuré votre instance Edge Microgateway avant la version 2.5.2, vous devez exécuter les deux commandes suivantes pour mettre à niveau le KVM et la règle d'authentification:

upgradekvm -o $ORG -e $ENV -u $USERNAME

Pour plus d'informations sur cette commande, consultez Mettre à niveau la KVM.

La commande suivante met à niveau le proxy edgemicro-oauth déployé sur votre organisation Apigee lorsque vous avez configuré Edge Microgateway. Ce proxy fournit les services requis pour générer des jetons.

upgradeauth -o $ORG -e $ENV -u $USERNAME

Pour en savoir plus sur cette commande, consultez Mettre à niveau le proxy Edgemicro-auth.

Effectuer une rotation des clés

Ajoutez la ligne suivante à votre fichier ~/.edgemicro/org-env-config.yaml, dans laquelle vous devez spécifier l'organisation et l'environnement que vous avez configurés pour la micropasserelle:

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

Exécutez la commande de rotation des clés pour les alterner. Pour en savoir plus sur cette commande, consultez Effectuer une rotation des clés.

edgemicro rotatekey -o $ORG -e $ENV -u $USERNAME -k $KID_VALUE

Exemple :

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v12.5.0
current edgemicro version is 3.1.0
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

Le paramètre -k spécifie un ID de clé (kid). Cet ID permet de cibler une clé spécifique. Edge Microgateway utilise cette valeur pour choisir parmi un ensemble de clés lors de la rotation des clés. Pour en savoir plus, consultez la section 4.5 de la spécification de la clé Web JSON.

Après la rotation des clés, Edge renvoie plusieurs clés à Edge Microgateway. Notez que dans l'exemple suivant, chaque clé a une valeur "kid" (ID de clé) unique. Elle utilise ensuite ces clés pour valider les jetons d'autorisation. Si la validation du jeton échoue, la micropasserelle vérifie si l'ensemble de clés contient une clé plus ancienne et tente de l'exécuter. Les clés renvoyées sont au format JSON Web Key (JWK). Pour en savoir plus sur ce format, consultez la RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Filtrer les proxys téléchargés

Par défaut, Edge Microgateway télécharge tous les proxys de votre organisation Edge qui commencent par le préfixe de nommage "edgemicro_". Vous pouvez modifier cette valeur par défaut pour télécharger les proxys dont les noms correspondent à un modèle.

1. Ouvrez votre fichier de configuration Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Ajoutez l'élément proxyPattern sous Edge_config. Par exemple, le modèle suivant télécharge des proxys tels que Edgemicro_foo, Edgemicro_fast et Edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Spécifier des produits sans proxy d'API

Dans Apigee Edge, vous pouvez créer un produit d'API ne contenant aucun proxy d'API. Cette configuration de produit permet à une clé API associée à ce produit de fonctionner avec tout proxy déployé dans votre organisation. À partir de la version 2.5.4, Edge Microgateway est compatible avec cette configuration de produit.

Débogage et dépannage

Se connecter à un débogueur

Vous pouvez exécuter Edge Microgateway avec un débogueur, tel que node-inspector. Cela est utile pour résoudre les problèmes liés aux plug-ins personnalisés et les déboguer.

1. Redémarrez Edge Microgateway en mode débogage. Pour ce faire, ajoutez DEBUG=* au début de la commande start :

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Pour diriger le résultat du débogage vers un fichier, vous pouvez utiliser la commande suivante :

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. Démarrez le débogueur et configurez-le pour écouter sur le numéro de port du processus de débogage.
3. Vous pouvez à présent parcourir le code Edge Microgateway, définir des points d'arrêt, des expressions de surveillance, etc.

Vous pouvez spécifier des indicateurs Node.js standards liés au mode débogage. Par exemple, --nolazy facilite le débogage du code asynchrone.

Vérifier des fichiers journaux

En cas de problème, veillez à examiner les fichiers journaux pour connaître les détails d'exécution et les erreurs. Pour en savoir plus, consultez Gérer les fichiers journaux.

Utiliser la sécurité des clés API

Les clés API fournissent un mécanisme simple pour authentifier les clients effectuant des requêtes à Edge Microgateway. Vous pouvez obtenir une clé API en copiant la valeur "Clé client" (également appelée "ID client") à partir d'un produit Apigee Edge incluant le proxy d'authentification Edge Microgateway.

Mise en cache des clés

Les clés API sont échangées contre des jetons de support, qui sont mis en cache. Vous pouvez désactiver la mise en cache en définissant l'en-tête Cache-Control: no-cache sur les requêtes entrantes vers Edge Microgateway.

Utiliser une clé API

Vous pouvez transmettre la clé API dans une requête API en tant que paramètre de requête ou dans un en-tête. Par défaut, l'en-tête et le nom du paramètre de requête sont x-api-key.

Exemple de paramètre de requête:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Exemple d'en-tête :

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Configurer le nom de la clé API

Par défaut, x-api-key est le nom utilisé pour l'en-tête de la clé API et le paramètre de requête. Vous pouvez modifier cette valeur par défaut dans le fichier de configuration, comme expliqué dans la section Modifier la configuration. Par exemple, pour remplacer le nom par apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

Dans cet exemple, le paramètre de requête et le nom de l'en-tête sont remplacés par apiKey. Dans les deux cas, le nom x-api-key ne fonctionnera plus. Consultez également la section Modifier la configuration.

Exemple :

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Pour en savoir plus sur l'utilisation de clés API avec des requêtes proxy, consultez Secure Edge Microgateway.

Activer les codes de réponse en amont

Par défaut, le plug-in oauth ne renvoie que les codes d'état d'erreur 4xx si la réponse n'est pas un état 200. Vous pouvez modifier ce comportement afin qu'il renvoie toujours le code 4xx ou 5xx exact, en fonction de l'erreur.

Pour activer cette fonctionnalité, ajoutez la propriété oauth.useUpstreamResponse: true à votre configuration Edge Microgateway. Exemple :

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Utiliser la sécurité des jetons OAuth2

Cette section explique comment obtenir des jetons d'accès OAuth2 et actualiser les jetons. Les jetons d'accès permettent d'effectuer des appels d'API sécurisés via la micropasserelle. Les jetons d'actualisation permettent d'obtenir de nouveaux jetons d'accès.

Obtenir un jeton d'accès

Cette section explique comment utiliser le proxy edgemicro-auth pour obtenir un jeton d'accès.

Vous pouvez également obtenir un jeton d'accès à l'aide de la commande CLI edgemicro token. Pour en savoir plus sur la CLI, consultez Gérer les jetons.

API 1: Envoyer des identifiants en tant que paramètres de corps

Remplacez le nom du client et de l'environnement par l'URL, et remplacez les valeurs ID client et Code secret client obtenues depuis une application de développement sur Apigee Edge par les paramètres du corps client_id et client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: Envoyer des identifiants dans un en-tête d'authentification de base

Envoyez les identifiants client sous la forme d'un en-tête d'authentification de base et grant_type comme paramètre de formulaire. Ce formulaire de commande est également décrit dans le document RFC 6749: OAuth 2.0 Authorization Framework.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Exemple de résultat

L'API renvoie une réponse JSON. Notez qu'il n'y a aucune différence entre les propriétés token et access_token. Vous pouvez utiliser l'une ou l'autre.

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Comment obtenir un jeton d'actualisation

Pour obtenir un jeton d'actualisation, effectuez un appel d'API au point de terminaison /token du proxy edgemicro-auth. Vous DEVEZ effectuer cet appel d'API avec le type d'octroi password. Les étapes suivantes vous guident tout au long du processus.

1. Obtenez un jeton d'accès et d'actualisation avec l'API /token. Notez que le type d'octroi est password :

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   .

   L'API renvoie un jeton d'accès et un jeton d'actualisation. La réponse ressemble à ceci:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Vous pouvez maintenant utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès en appelant le point de terminaison /refresh de la même API. Exemple :

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   L'API renvoie un nouveau jeton d'accès. La réponse ressemble à ceci:

   {
       "token": "your-new-access-token"
       }

Surveillance indéfinie

Forever est un outil Node.js qui redémarre automatiquement une application Node.js en cas de panne ou d'erreur. Edge Microgateway possède un fichier forever.json que vous pouvez configurer pour contrôler le nombre de redémarrages et les intervalles de redémarrage d'Edge Microgateway. Ce fichier configure un service Forever appelé forever-monitor, qui gère le programmatique Forever.

Le fichier forever.json se trouve dans le répertoire d'installation racine d'Edge Microgateway. Consultez Où est installé Edge Microgateway. Pour en savoir plus sur les options de configuration, consultez la documentation Forever-Monitor.

La commande edgemicro forever inclut des indicateurs qui vous permettent de spécifier l'emplacement du fichier forever.json (indicateur -f) et de démarrer/arrêter le processus de surveillance permanente (indicateur -a). Exemple :

edgemicro forever -f ~/mydir/forever.json -a start

Pour en savoir plus, consultez la section Surveillance permanente dans la documentation de référence de la CLI.

Spécifier un point de terminaison de fichier de configuration

Si vous exécutez plusieurs instances Edge Microgateway, vous pouvez gérer leurs configurations à partir d'un seul emplacement. Pour ce faire, spécifiez un point de terminaison HTTP sur lequel Edge Micro peut télécharger son fichier de configuration. Vous pouvez spécifier ce point de terminaison lorsque vous démarrez Edge Micro à l'aide de l'indicateur -u.

Exemple :

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

où le point de terminaison mgconfig renvoie le contenu de votre fichier de configuration. Il s'agit du fichier qui se trouve par défaut dans ~/.edgemicro et qui respecte la convention d'attribution de noms : org-env-config.yaml.

Désactiver la mise en mémoire tampon des données de connexion TCP

Vous pouvez utiliser l'attribut de configuration nodelay pour désactiver la mise en mémoire tampon des données pour les connexions TCP utilisées par Edge Microgateway.

Par défaut, les connexions TCP utilisent l'algorithme Nagle pour mettre en mémoire tampon les données avant de les envoyer. Définir nodelay sur true désactive ce comportement (les données sont immédiatement déclenchées à chaque appel de socket.write()). Pour en savoir plus, consultez également la documentation de Node.js.

Pour activer nodelay, modifiez le fichier de configuration Edge Micro comme suit:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Exécution d'Edge Microgateway en mode autonome

Vous pouvez exécuter Edge Microgateway entièrement déconnecté de toute dépendance Apigee Edge. Ce scénario, appelé mode autonome, vous permet d'exécuter et de tester Edge Microgateway sans connexion Internet.

En mode autonome, les fonctionnalités suivantes ne fonctionnent pas, car elles nécessitent une connexion à Apigee Edge:

• OAuth et clé API
• Quotas
• Analytics

En revanche, les plug-ins personnalisés et l'arrêt des pics fonctionnent normalement, car ils ne nécessitent pas de connexion à Apigee Edge. De plus, un nouveau plug-in appelé extauth vous permet d'autoriser les appels d'API à la micropasserelle avec un jeton JWT en mode autonome.

Configurer et démarrer la passerelle

Pour exécuter Edge Microgateway en mode autonome:

1. Créez un fichier de configuration nommé comme suit: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   Exemple :

   vi $HOME/.edgemicro/foo-bar-config.yaml

2. Collez le code suivant dans le fichier :

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

3. Exportez la variable d'environnement suivante avec la valeur "1" :

   export EDGEMICRO_LOCAL=1

4. Exécutez la commande start suivante, dans laquelle vous fournissez des valeurs pour instancier le proxy local :

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   Où :

   • $ORG est le nom "org" que vous avez utilisé dans le nom du fichier de configuration.
   • $ENV est le nom "env" que vous avez utilisé dans le nom du fichier de configuration.
   • $LOCAL_PROXY_NAME est le nom du proxy local qui sera créé. Vous pouvez utiliser le nom de votre choix.
   • $LOCAL_PROXY_VERSION est le numéro de version du proxy.
   • $TARGET_URL est l'URL de la cible du proxy. (La cible est le service appelé par le proxy.)
   • $BASE_PATH est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin de base racine, ajoutez une barre oblique, par exemple, "/".

   Exemple :

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

5. Tester la configuration

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Comme le plug-in extauth se trouve dans le fichier foo-bar-config.yaml, une erreur "missing_authorization" est renvoyée. Ce plug-in valide un jeton JWT qui doit être présent dans l'en-tête Authorization de l'appel d'API. Dans la section suivante, vous allez obtenir un jeton JWT qui permettra de passer les appels d'API sans erreur.

Exemple: Obtenir un jeton d'autorisation

L'exemple suivant montre comment obtenir un jeton JWT à partir du point de terminaison JWT Edge Microgateway sur Apigee Edge (edgemicro-auth/jwkPublicKeys). Ce point de terminaison est déployé lorsque vous effectuez une configuration standard d'Edge Microgateway. Pour obtenir le JWT depuis le point de terminaison Apigee, vous devez d'abord effectuer la configuration standard d'Edge Microgateway et être connecté à Internet. Le point de terminaison Apigee n'est utilisé ici qu'à des fins d'exemple et n'est pas obligatoire. Si vous le souhaitez, vous pouvez utiliser un autre point de terminaison du jeton JWT. Dans ce cas, vous devrez obtenir le JWT à l'aide de l'API fournie pour ce point de terminaison.

Les étapes suivantes expliquent comment obtenir un jeton à l'aide du point de terminaison edgemicro-auth/jwkPublicKeys :

1. Vous devez effectuer une configuration et une configuration standards d'Edge Microgateway pour déployer le proxy edgemicro-auth dans votre organisation/environnement sur Apigee Edge. Si vous avez déjà effectué cette étape, vous n'avez pas besoin de la répéter.
2. Si vous avez déployé Edge Microgateway sur Apigee Cloud, vous devez être connecté à Internet pour obtenir un jeton JWT à partir de ce point de terminaison.
3. Arrêtez Edge Microgateway :

   edgemicro stop

4. Dans le fichier de configuration que vous avez créé précédemment ($HOME/.edgemicro/org-env-config.yaml), faites pointer l'attribut extauth:publickey_url vers le point de terminaison edgemicro-auth/jwkPublicKeys de votre organisation/environnement Apigee Edge. Exemple :

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Redémarrez Edge Microgateway comme vous le faisiez précédemment, en utilisant les noms org/env que vous avez utilisés dans le nom du fichier de configuration. Exemple :

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Obtenez un jeton JWT à partir du point de terminaison de l'autorisation. Comme vous utilisez le point de terminaison edgemicro-auth/jwkPublicKeys, vous pouvez utiliser la commande CLI suivante :

Vous pouvez générer un jeton JWT pour Edge Microgateway à l'aide de la commande edgemicro token ou d'une API. Exemple :

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Où :

• your_org est le nom de votre organisation Apigee pour laquelle vous avez précédemment configuré Edge Microgateway.
• your_env est un environnement de l'organisation.
• L'option i spécifie la clé client d'une application de développement contenant un produit qui inclut le proxy edgemicro-auth.
• L'option s spécifie le code secret client d'une application de développement incluant un produit qui inclut le proxy edgemicro-auth.

Cette commande demande à Apigee Edge de générer un jeton JWT qui peut ensuite être utilisé pour vérifier les appels d'API.

Consultez également la section Générer un jeton.

Tester la configuration autonome

Pour tester la configuration, appelez l'API avec le jeton ajouté dans l'en-tête comme suit:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Exemple :

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Exemple de résultat :

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Utiliser le mode proxy local

En mode proxy local, Edge Microgateway ne nécessite pas de déploiement de proxy microgateway-aware pour être déployé sur Apigee Edge. À la place, vous configurez un "proxy local" en fournissant un nom de proxy local, un chemin de base et une URL cible lorsque vous démarrez la micropasserelle. Les appels d'API à la micropasserelle sont ensuite envoyés à l'URL cible du proxy local. À tous les autres égards, le mode proxy local fonctionne exactement comme l'exécution d'Edge Microgateway en mode normal. L'authentification fonctionne de la même manière que l'application des quotas et l'application des quotas, les plug-ins personnalisés, etc.

Cas d'utilisation et exemple

Le mode proxy local est utile lorsque vous n'avez besoin d'associer qu'un seul proxy à une instance Edge Microgateway. Par exemple, vous pouvez injecter Edge Microgateway dans Kubernetes en tant que proxy side-car, où une micropasserelle et un service s'exécutent chacun dans un seul pod, et où elle gère le trafic vers et depuis son service associé. La figure suivante illustre cette architecture dans laquelle Edge Microgateway sert de proxy side-car dans un cluster Kubernetes. Chaque instance de micropasserelle ne communique qu'avec un seul point de terminaison sur son service associé:

L'un des avantages de ce style d'architecture est qu'Edge Microgateway permet de gérer les API pour des services individuels déployés dans un environnement de conteneurs, tels qu'un cluster Kubernetes.

Configurer le mode proxy local

Pour configurer Edge Microgateway pour l'exécuter en mode proxy local, procédez comme suit:

1. Exécutez edgemicro init pour définir votre environnement de configuration local, exactement comme vous le feriez avec une configuration Edge Microgateway standard. Consultez également la section Configurer Edge Microgateway.
2. Exécutez edgemicro configure, comme vous le feriez dans une procédure de configuration Edge Microgateway standard. Exemple :

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Cette commande déploie la stratégie edgemicro-auth sur Edge et renvoie une clé et un code secret dont vous aurez besoin pour démarrer la micropasserelle. Si vous avez besoin d'aide, consultez Configurer Edge Microgateway.

3. Sur Apigee Edge, créez un produit d'API en respectant les exigences de configuration obligatoires suivantes (vous pouvez gérer toutes les autres configurations comme vous le souhaitez) :
   • Vous devez ajouter le proxy edgemicro-auth au produit. Ce proxy a été déployé automatiquement lorsque vous avez exécuté edgemicro configure.
   • Vous devez fournir un chemin d'accès à la ressource. Apigee recommande d'ajouter le chemin d'accès suivant au produit: /**. Pour en savoir plus, consultez Configurer le comportement du chemin d'accès à la ressource. Voir également Créer des produits d'API dans la documentation Edge.

4. Sur Apigee Edge, créez un développeur. Vous pouvez également utiliser un développeur existant si vous le souhaitez. Pour obtenir de l'aide, consultez Ajouter des développeurs à l'aide de l'interface utilisateur de gestion Edge.

5. Sur Apigee Edge, créez une application de développement. Vous devez ajouter le produit d'API que vous venez de créer à l'application. Pour obtenir de l'aide, consultez Enregistrer une application dans l'interface de gestion Edge.
6. Sur la machine sur laquelle Edge Microgateway est installé, exportez la variable d'environnement suivante avec la valeur "1".

   export EDGEMICRO_LOCAL_PROXY=1

7. Exécutez la commande start suivante :

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Où :

   • your_org est votre organisation Apigee.
   • your_environment est un environnement de votre organisation.
   • your_key est la clé renvoyée lors de l'exécution de edgemicro configure.
   • your_secret est le secret renvoyé lorsque vous avez exécuté edgemicro configure.
   • local_proxy_name est le nom du proxy local qui sera créé.
   • local_proxy_version est le numéro de version du proxy.
   • target_url est l'URL de la cible du proxy (le service que le proxy appelle).
   • base_path est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin de base racine, ajoutez une barre oblique, par exemple, "/".

   Exemple :

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Tester la configuration

Vous pouvez tester la configuration du proxy local en appelant le point de terminaison du proxy. Par exemple, si vous avez spécifié le chemin de base /echo, vous pouvez appeler le proxy comme suit:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Cet appel d'API initial a généré une erreur, car vous n'avez pas fourni de clé API valide. Vous trouverez la clé dans l'application de développeur que vous avez créée précédemment. Ouvrez l'application dans l'interface utilisateur Edge, copiez la clé client et utilisez-la comme suit:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Exemple :

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Exemple de résultat :

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

Utiliser le synchroniseur

Cette section explique comment utiliser le synchronisateur, une fonctionnalité facultative qui améliore la résilience d'Edge Microgteway en lui permettant de récupérer des données de configuration d'Apigee Edge et de les écrire dans une base de données Redis locale. Lorsqu'une instance de synchronisation est en cours d'exécution, d'autres instances Edge Microgateway exécutées sur différents nœuds peuvent récupérer leur configuration directement à partir de cette base de données.

La fonctionnalité de synchronisation est actuellement compatible avec Redis 5.0.x.

Qu'est-ce que le synchronisateur ?

Le synchroniseur offre un niveau de résilience pour Edge Microgateway. Elle garantit que chaque instance d'Edge Microgateway utilise la même configuration et qu'en cas de perturbation Internet, les instances Edge Microgateway peuvent démarrer et s'exécuter correctement.

Par défaut, les instances Edge Microgateway doivent pouvoir communiquer avec Apigee Edge pour récupérer et actualiser leurs données de configuration, telles que les configurations de proxy d'API et de produit d'API. Si la connexion Internet avec Edge est interrompue, les instances de micropasserelle peuvent continuer à fonctionner, car les données de configuration les plus récentes sont mises en cache. Cependant, les nouvelles instances de micropasserelle ne peuvent pas démarrer sans connexion claire. En outre, il est possible qu'une perturbation Internet entraîne l'exécution d'une ou de plusieurs instances de micropasserelle avec des informations de configuration non synchronisées avec les autres instances.

Le synchronisateur Edge Microgateway fournit un autre mécanisme pour les instances Edge Microgateway permettant de récupérer les données de configuration dont elles ont besoin pour démarrer et traiter le trafic proxy de l'API. Le synchronisateur permet à toutes les instances Edge Microgateway de s'exécuter sur différents nœuds de démarrer correctement et de rester synchronisées même si la connexion Internet entre Edge Microgateway et Apigee Edge est interrompue.

Le synchroniseur est une instance spécialement configurée d'Edge Microgateway. Son seul objectif est d'interroger Apigee Edge (le timing est configurable), de récupérer les données de configuration et de les écrire dans une base de données Redis locale. L'instance de synchronisation elle-même ne peut pas traiter le trafic de proxy d'API. D'autres instances d'Edge Microgateway exécutées sur différents nœuds peuvent être configurées pour récupérer des données de configuration à partir de la base de données Redis plutôt qu'à partir d'Apigee Edge. Étant donné que toutes les instances de micropasserelle extraient leurs données de configuration de la base de données locale, elles peuvent démarrer et traiter des requêtes API même en cas de perturbation Internet.

Configurer une instance de synchronisation

Ajoutez la configuration suivante au fichier org-env/config.yaml de l'installation Edge Microgateway que vous souhaitez utiliser en tant que synchronisé :

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Exemple :

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Option	Description
redisHost	Hôte sur lequel votre instance Redis est en cours d'exécution. Par défaut: 127.0.0.1
redisPort	Port de l'instance Redis. Par défaut: 6379
redisDb	Base de données Redis à utiliser. Par défaut: 0
redisPassword	Mot de passe de votre base de données.

Enfin, enregistrez le fichier de configuration et démarrez l'instance Edge Microgateway. Elle commencera à interroger Apigee Edge et à stocker les données de configuration téléchargées dans la base de données Redis.

Configuration d'instances Edge Microgateway standards

Une fois le synchroniseur en cours d'exécution, vous pouvez configurer des nœuds Edge Microgateway supplémentaires pour exécuter des instances de micropasserelles standards qui traitent le trafic proxy de l'API. Cependant, vous configurez ces instances pour obtenir leurs données de configuration à partir de la base de données Redis plutôt qu'à partir d'Apigee Edge.

Ajoutez la configuration suivante au fichier org-env/config.yaml de chaque nœud Edge Microgateway supplémentaire. Notez que la propriété synchronizerMode est définie sur 0. Cette propriété définit l'instance pour qu'elle fonctionne comme une instance périphérique Edge Microgateway qui traite le trafic de proxy d'API. L'instance obtiendra ses données de configuration à partir de la base de données Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Exemple :

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Propriétés de configuration

Les propriétés de configuration suivantes ont été ajoutées pour permettre l'utilisation de la synchronisation:

Attribut	Valeurs	Description
edge_config.synchronizerMode	0 ou 1	Si celle-ci est nulle (par défaut), Edge Microgateway fonctionne en mode standard. Si c'est le cas, démarrez l'instance Edge Microgateway pour la synchroniser. Dans ce mode, l'instance extrait les données de configuration d'Apigee Edge et les stocke dans une base de données Redis locale. Cette instance n'est pas en mesure de traiter les requêtes de proxy d'API. Son seul objectif est d'interroger Apigee Edge pour obtenir des données de configuration et de les écrire dans la base de données locale. Vous devez ensuite configurer d'autres instances de micropasserelle pour lire les données de la base de données.
edge_config.redisBasedConfigCache	vrai ou faux	Si la valeur est "true", l'instance Edge Microgateway récupère ses données de configuration à partir de la base de données Redis au lieu d'Apigee Edge. La base de données Redis doit être identique à celle dans laquelle le synchroniseur est configuré pour écrire. Si la base de données Redis est indisponible ou si la base de données est vide, la micropasserelle recherche un fichier cache-config.yaml existant pour sa configuration. Si la valeur est définie sur "false" (valeur par défaut), l'instance Edge Microgateway récupère les données de configuration d'Apigee Edge comme d'habitude.
edgemicro.config_change_poll_interval	Intervalle de temps, en secondes	Spécifie l'intervalle d'interrogation pour le synchronisé afin d'extraire les données d'Apigee Edge.