Utiliser Docker pour Edge Microtation

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

Cet article explique comment exécuter Edge Microgateway dans un conteneur Docker. Les étapes décrites dans cette rubrique supposent une compréhension de base de Docker, des commandes Docker, ainsi que de la configuration et de la configuration d'Edge Microgateway. Pour en savoir plus, consultez la documentation de Docker et Edge Microgateway.

Prérequis

Avant d'exécuter Edge Microgateway dans un conteneur Docker, vous devez effectuer les tâches suivantes :

  • Configurez Edge Microgateway pour votre organisation/environnement Apigee :

    edgemicro configure -o your_org -e your_env -u your_username

    Pour en savoir plus sur la configuration, consultez Partie 1 : Configurer Edge Microgateway.

  • Après avoir effectué les étapes de configuration, localisez le fichier de configuration. L'emplacement par défaut est le suivant :

    $HOME/.edgemicro/your_org-your_env-config.yaml

    où your_org et your_env correspondent à l'organisation et à l'environnement que vous avez utilisés lorsque vous avez exécuté la commande edgemicro config. Vous aurez besoin de ce fichier lorsque vous démarrerez Edge Microgateway dans un conteneur Docker.

  • Assurez-vous de disposer des identifiants de clé et de code secret qui ont été renvoyés lorsque vous avez exécuté la commande edgemicro config. Exemple :

    The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

  • Avant de démarrer Edge Microgateway dans un conteneur Docker, vous devez créer (ou avoir créé) les entités Apigee Edge requises pour effectuer des appels authentifiés de proxy d'API. Ces entités incluent un proxy compatible avec Edge Microgateway, un produit d'API, un développeur et une application de développeur. Pour obtenir des instructions complètes, consultez Créer des entités sur Apigee Edge.

Exécuter Edge Micro en tant que conteneur Docker

  1. Téléchargez l'image Docker pour Edge Microgateway :

    docker pull gcr.io/apigee-microgateway/edgemicro:latest

  2. Avant de passer aux étapes suivantes, assurez-vous d'avoir effectué toutes les étapes de la section Conditions préalables.

  3. Exécutez la commande suivante pour encoder en base64 le fichier de configuration Edge Microgateway situé dans $HOME/.edgemicro :

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    où your_org et your_env sont l'organisation et l'environnement que vous avez utilisés lorsque vous avez exécuté la commande edgemicro config.

    N'oubliez pas de placer des accents graves (`) autour de la commande. Exemple :

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. Exécutez Edge Microgateway en tant que conteneur. La commande définit plusieurs variables d'environnement utilisées par l'environnement d'exécution du conteneur pour démarrer Edge Microgateway :

    chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e "LOG_CONSOLE_OUTPUT_TO_FILE=false" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL \
gcr.io/apigee-microgateway/edgemicro:latest

    Paramètres

      <tr>
    <td><code>SERVICE_NAME</code></td>
    <td>If you are on Kubernetes, this parameter is auto-populated. Otherwise,
      you can set it to anything you wish. If you specify nothing, the service
      name is set to <code>default</code>.</td>
  </tr>
  <tr>
    <tr>
    <td><code>DEBUG</code></td>
    <td>Set to <code>*</code> to enable debugging. </td>
  </tr>
  <tr>
    <td><code>HTTP_PROXY</code>
        <code>HTTPS_PROXY</code></td>
    <td>Use when Edge Microgateway is
      running behind a firewall and the gateway cannot communicate with Apigee
      Edge. For more
      information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>. 
      <p>For example: <code>HTTP_PROXY=http://10.203.0.1:5187/</code></p></td>
  </tr>
  <tr>
    <td><code>NO_PROXY</code></td>
    <td>A comma delimited list of domains that Edge Microgateway should not proxy to. 
      For more information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>.
      <p>For example: <code>localhost,127.0.0.1,localaddress,.localdomain.com</code></p></td>
  </tr>
  <tr>
  <tr>
    <tr>
    <td><code>NODE_EXTRA_CA_CERTS</code></td>
    <td>(Optional) Use this parameter if you are using a CA that's not trusted
      by default by Node.js. Set the value of this parameter to the path to a
      file containing one or more trusted certificates in PEM format. For
      details, see <a href="#tls_certificates">TLS certificates</a>.</td>
  </tr>
  <tr>
    <td><code>--security-opt</code></td>
    <td>(Optional) Sets desired Docker security options. See <a href="https://docs.docker.com/engine/reference/run/#security-configuration">Security configuration</a> in the Docker documentation.</td>
  </tr>
  <tr>
    <td><code>--cap-drop</code></td>
    <td>(Optional) Sets limits on Linux capabilities permitted in the container. See <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">Runtime privilege and Linux capabilities</a> in the Docker documentation.</td>
  </tr>
</tbody>

    Paramètre Description
    -P Publiez tous les ports exposés sur l'hôte. Consultez également la documentation de référence sur l'exécution de Docker.
    -p Mappez explicitement un seul port ou une plage de ports. Consultez également la documentation de référence sur l'exécution de Docker.
    -d Exécutez en mode détaché. Consultez également la documentation de référence sur l'exécution de Docker.
    -v, -- volume Spécifie un montage de volume. Notez que si vous configurez Edge Microgateway pour utiliser TLS dans le conteneur Docker, vous devez exposer le port 8443 si vous montez le répertoire du fichier journal. Voir aussi VOLUME [systèmes de fichiers partagés]. Consultez également Utiliser TLS dans le conteneur Docker.
    -w, -- workdir (Facultatif) Spécifie le chemin d'accès au répertoire dans lequel les fichiers edgemicro.sock et edgemicro.pid doivent être créés. Vous ne pouvez pas modifier la racine du nom de fichier edgemicro. Par défaut, il s'agit du chemin d'accès au répertoire de travail actuel.

    Exemple : 

    docker run -P -p 8000:8000 -d -w /tmp --name edgemicro 
    
...
    EDGEMICRO_ORG Nom de l'organisation Apigee que vous avez utilisée pour configurer Edge Microgateway.
    EDGEMICRO_ENV Nom de l'environnement Apigee que vous avez utilisé pour configurer Edge Microgateway.
    EDGEMICRO_PROCESSES Nombre de processus à démarrer.
    EDGEMICRO_KEY Clé renvoyée lorsque vous avez configuré Edge Microgateway.
    EDGEMICRO_SECRET Secret renvoyé lorsque vous avez configuré Edge Microgateway.
    EDGEMICRO_CONFIG Variable contenant le fichier de configuration Edge Microgateway encodé en base64.
    LOG_CONSOLE_OUTPUT_TO_FILE (Booléen) Vous permet de spécifier où envoyer la sortie du journal. Consultez Spécifier les options du fichier journal.

    Exemple :

    chown -R 100:101 ~/.edgemicro/ 
    
  docker run -P -p 8000:8000 -d --name edgemicro 
    
  -v /var/tmp:/opt/apigee/logs 
    
  -e EDGEMICRO_PROCESS=1 
    
  -e EDGEMICRO_ORG=docs 
    
  -e EDGEMICRO_ENV=test 
    
  -e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 
    
  -e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 
    
  -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" 
    
  -e SERVICE_NAME=edgemicro 
    
  --security-opt=no-new-privileges 
    
  --cap-drop=ALL 
    
  gcr.io/apigee-microgateway/edgemicro

    1. Pour vérifier que le conteneur est en cours d'exécution :

      docker ps

      La sortie obtenue doit ressembler à ceci :

      CONTAINER ID    IMAGE         COMMAND                CREATED          STATUS          PORTS                                             NAMES
8b92e082ea9c    edgemicro    "/tmp/entrypoint.sh"   12 minutes ago   Up 12 minutes    0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp    edgemicro

    Spécifier les options de sortie du fichier journal

    Le paramètre de configuration Edge Microgateway to_console vous permet de choisir d'envoyer les informations de journal à la sortie standard plutôt qu'à un fichier journal. Si vous suivez la procédure pour exécuter Edge Microgateway dans un conteneur Docker, le conteneur redirige par défaut la sortie stdout et les messages d'erreur vers un fichier situé dans le conteneur à l'emplacement ${APIGEE_ROOT}/logs/edgemicro.log.

    Pour empêcher l'envoi d'informations de journal à edgemicro.log, utilisez la variable LOG_CONSOLE_OUTPUT_TO_FILE lorsque vous exécutez le conteneur.

    Le tableau suivant décrit le comportement de la sortie du journal lorsque vous utilisez LOG_CONSOLE_OUTPUT_TO_FILE avec to_console :

    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=false

    • Aucun journal ne sera envoyé au fichier journal Edge Microgateway, comme décrit dans Gérer les fichiers journaux.
    • Les journaux ne seront pas envoyés au fichier edgemicro.log.
    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • Aucun journal ne sera envoyé au fichier journal Edge Microgateway, comme décrit dans Gérer les fichiers journaux.
    • Les journaux seront envoyés au fichier edgemicro.log.
    to_console: false

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • Les journaux seront envoyés au fichier journal Edge Microgateway, comme décrit dans Gérer les fichiers journaux.
    • Les journaux seront envoyés au fichier edgemicro.log.

    Tester un appel d'API

    Une fois qu'Edge Microgateway est démarré dans le conteneur, vous pouvez lui envoyer des appels d'API. Par exemple, si le chemin de base de votre API est /hello :

    http://localhost:8000/hello

    Exemple de résultat :

    {"error":"missing_authorization","error_description":"Missing Authorization header"}

    Si cette réponse s'affiche, cela signifie qu'Edge Microgateway a correctement géré l'appel d'API. Toutefois, par défaut, Edge Microgateway nécessite une clé API pour l'authentification. Dans la section suivante, vous allez tester l'API avec une clé API valide.

    Tester une API avec une clé API valide

    Dans l'interface utilisateur Edge, accédez à l'application de développeur que vous avez créée précédemment. Sur la page "Developer App" (Application de développeur), affichez la clé client et copiez-la. Cette valeur correspond à la clé API. Vous utiliserez cette clé pour effectuer des appels d'API authentifiés.

    Appelez l'API avec l'en-tête x-api-key comme suit. La valeur de la clé client que vous avez copiée à partir de l'application de développement correspond à la clé API. Par défaut, Edge Microgateway s'attend à ce que vous transmettiez la clé dans un en-tête appelé x-api-key, comme suit :

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    Exemple :

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

    Pour en savoir plus sur l'authentification des appels d'API via Edge Microgateway avec des clés API et des jetons OAuth, consultez la partie 4 : Sécuriser Edge Microgateway.

    Arrêter Edge Microgateway

    Utilisez la commande Docker suivante pour arrêter Edge Microgateway :

    docker stop edgemicro

    Redémarrer Edge Microgateway

    Après avoir arrêté Edge Microgateway, vous pouvez le redémarrer avec cette commande Docker :

    docker start edgemicro

    Utiliser TLS dans le conteneur Docker

    Cette section explique comment configurer TLS pour Edge Microgateway s'exécutant dans un conteneur Docker. Vous pouvez configurer le serveur Edge Microgateway pour qu'il utilise TLS pour les requêtes entrantes (direction nord) et vous pouvez configurer Edge Microgateway pour qu'il soit un client TLS pour les requêtes sortantes vers les points de terminaison cibles (direction sud).

    Où placer les fichiers de certificat

    Le conteneur Docker exécutant Edge Microgateway dispose d'un point d'installation sur /opt/apigee/.edgemicro. Lorsque vous configurez Edge Microgateway pour qu'il utilise des certificats TLS, vous pouvez rendre les fichiers de certificat disponibles sur ce point de montage et y faire référence dans le fichier de configuration Edge Microgateway. Ce fichier de configuration se trouve généralement dans le répertoire $HOME/.edgemicro et est nommé your_org-your_env-config.yaml. Exemple :

    ...
edgemicro:
  ssl:
   key: /opt/apigee/.edgemicro/southbound/tls.key
   cert: /opt/apigee/.edgemicro/southbound/tls.crt
...

    Utiliser une autorité de certification non approuvée par Node.js

    Si vous utilisez une autorité de certification (CA) qui n'est pas approuvée par défaut par Node.js (comme c'est le cas avec un certificat autosigné), envisagez d'utiliser le paramètre NODE_EXTRA_CA_CERTS lorsque vous exécutez le conteneur.

    Définissez ce paramètre sur le chemin d'accès à un fichier contenant un ou plusieurs certificats approuvés au format PEM. Pour voir comment ce paramètre est utilisé, consultez les exemples Configurer TLS vers le nord et Configurer TLS vers le sud.

    Exemple :

    chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

    Consultez également Exécuter Edge Micro en tant que conteneur Docker.

    Désactiver la validation TLS

    Bien que cela ne soit pas recommandé, vous pouvez, dans certains cas, désactiver la validation TLS pour Edge Microgateway exécuté dans un conteneur. La possibilité de désactiver TLS n'est pas intégrée par défaut au conteneur Docker Edge Microgateway. Pour ce faire, vous devez créer une image Docker personnalisée pour Edge Microgateway. Vous trouverez ci-dessous des instructions générales pour créer l'image personnalisée et désactiver la validation TLS.

    1. Clonez ou téléchargez le dépôt source Edge Microgateway depuis https://github.com/apigee-internal/microgateway.

    2. cd dans le répertoire microgateway/kubernetes/docker/edgemicro du répertoire de code source.

      Exemple :

      cd $HOME/git/microgateway/kubernetes/docker/edgemicro

    3. Ouvrez le fichier entrypoint.sh et modifiez le code pour accepter la variable d'environnement NODE_TLS_REJECT_UNAUTHORIZED. Plus tard, lorsque vous exécuterez le conteneur, vous spécifierez une valeur pour cette variable.

    4. Créez le conteneur Docker :

      docker build -t edgemicro .

    5. Lorsque vous exécutez le conteneur, spécifiez l'option -e NODE_TLS_REJECT_UNAUTHORIZED = 1. Exemple :

    chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_TLS_REJECT_UNAUTHORIZED = 1 \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

    Exemple : configurer le protocole TLS vers le nord

    Cette section explique comment configurer une connexion TLS northbound (entrante) sur le serveur Edge Microgateway. Le protocole TLS en amont permet aux clients d'utiliser HTTPS lorsqu'ils effectuent des appels d'API vers Edge Microgateway. L'exemple ci-dessous utilise des certificats autosignés.

    1. Étapes de configuration initiale

    1. Recherchez le fichier openssl.cnf sur votre système. Exemple :/etc/ssl/openssl.cnf
    2. Ouvrez le fichier opensssl.cnf pour le modifier.

    3. Assurez-vous que les req_extensions sont présents dans votre fichier de configuration. Par exemple, votre fichier doit contenir des informations semblables à celles ci-dessous :

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. Ajoutez le stanza suivant à openssl.cnf pour générer les bons attributs SNI :

      [ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

      Exemple de fichier opensssl.cnf :

      [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

    5. Suivez les étapes décrites dans la section Conditions requises pour initialiser et configurer Edge Microgateway, si vous ne l'avez pas déjà fait. Une fois terminé, vous devriez avoir créé un proxy compatible avec Edge Microgateway, un produit d'API, un développeur et une application de développeur. De plus, vous devriez avoir exécuté la commande edgemicro configure et reçu une clé et un code secret.

    2. Générer des certificats autosignés

    Ensuite, générez les certificats et les clés dont vous aurez besoin pour établir le protocole TLS :

    1. cd dans le répertoire $HOME/.edgemicro.

    2. Créez le script bash suivant. Vous pouvez lui donner le nom de votre choix. Exemple : keygen.sh.

      #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

    3. Dans le fichier bash, assurez-vous que le chemin d'accès au fichier openssl.cnf est correct.

    4. Exécutez le fichier bash. Vous serez invité à fournir des informations sur le certificat. Veillez à utiliser localhost pour le nom commun.

    5. Vérifiez que les fichiers suivants ont été créés :

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt

    3. Modifier le fichier de configuration Edge Microgateway

    1. Ouvrez le fichier de configuration Edge Micro dans un éditeur. Exemple :

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. Modifiez la stanza edgemicro comme suit. Notez que vous modifiez les attributs port et ssl :

      edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

    3. Exécutez la commande suivante pour encoder en base64 le fichier de configuration Edge Microgateway situé dans $HOME/.edgemicro :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      où your_org et your_env sont l'organisation et l'environnement que vous avez utilisés lorsque vous avez exécuté la commande edgemicro config.

      N'oubliez pas de placer des accents graves (`) autour de la commande. Exemple :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    Consultez également Exécuter Edge Micro en tant que conteneur Docker.

    4. Exécuter le conteneur

    1. Exécutez la commande suivante pour exécuter le conteneur Docker avec Edge Microgateway :

      chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
gcr.io/apigee-microgateway/edgemicro:latest

    2. Notez les paramètres suivants utilisés dans la commande. Ils diffèrent de la commande de base décrite dans Exécuter Edge Microgateway en tant que conteneur Docker.

      • La valeur de port est définie sur 8443.
      • Une installation de volume est utilisée pour installer les fichiers de clé et de certificat.
      • La variable NODE_EXTRA_CA_CERTS permet d'ajouter une AC personnalisée (si nécessaire dans le cas de certificats autosignés).

    5. Tester la configuration TLS

    1. Exécutez la commande cURL suivante pour tester la configuration. Remplacez votre chemin de base et votre clé API dans la commande. L'exemple suivant suppose que vous vous trouvez dans le répertoire où se trouve rootca.pem et que le proxy que vous avez créé a le chemin de base /hello :

      curl -v https://localhost:8443/hello --cacert rootca.pem \
-H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"

    2. La sortie cURL détaillée affiche chaque étape de l'établissement de liaison TLS. Si vous voyez une réponse HTTP 200, la configuration a réussi :

      *   Trying ::1...ey:Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
* TCP_NODELAY set
* Connected to localhost (::1) port 8443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: rootca.pem
  CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  start date: Dec 14 22:35:28 2018 GMT
*  expire date: Oct  3 22:35:28 2021 GMT
*  common name: localhost (matched)
*  issuer: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  SSL certificate verify ok.
> GET /hello HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key:Az82fdnfaONVCOE4NKhajxAboDA3FAo
>
< HTTP/1.1 200 OK
< x-powered-by: Apigee
< access-control-allow-origin: *
< x-frame-options: ALLOW-FROM RESOURCE-URL
< x-xss-protection: 1
< x-content-type-options: nosniff
< content-type: text/plain; charset=utf-8
< etag: W/"d-GHB1ZrJKk/wdVTdB/jgBsw"
< date: Fri, 14 Dec 2018 22:43:13 GMT
< via: 1.1 google
< alt-svc: clear
< x-response-time: 1325
< Connection: keep-alive
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
Hello, Guest!

    Exemple : Configurer le protocole TLS en aval

    Cette section explique comment configurer une connexion TLS Southbound (sortante) entre le serveur Edge Microgateway et une application cible de backend. L'exemple ci-dessous utilise des certificats autosignés.

    1. Étapes de configuration initiale

    1. Recherchez le fichier openssl.cnf sur votre système. Exemple :/etc/ssl/openssl.cnf
    2. Ouvrez le fichier opensssl.cnf pour le modifier.

    3. Assurez-vous que les req_extensions sont présents dans votre fichier de configuration. Par exemple, votre fichier doit contenir des informations semblables à celles ci-dessous :

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. Ajoutez le stanza suivant à openssl.cnf pour générer les bons attributs SNI :

      [ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

      Exemple de fichier opensssl.cnf :

      [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

    5. Exécutez la commande edgemicro configure :

      edgemicro configure -o your_org -e your_env -u your_username

      Pour en savoir plus sur la configuration, consultez Partie 1 : Configurer Edge Microgateway.

    6. Copiez les identifiants de clé et de code secret renvoyés par edgemicro configure. Vous aurez besoin de ces valeurs pour exécuter le conteneur. Exemple :

      The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

    2. Créer une application cible Node.js

    1. cd dans le répertoire .edgemicro.

    2. Créez le script bash suivant. Vous pouvez lui donner le nom de votre choix. Exemple : keygen.sh.

      #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

    3. Dans le fichier bash, assurez-vous que le chemin d'accès au fichier openssl.cnf est correct.

    4. Exécutez le fichier bash. Vous serez invité à fournir des informations sur le certificat. Veillez à utiliser hellworld pour le nom commun.

    5. Vérifiez que les fichiers suivants ont été créés :

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt

    6. Créez un fichier appelé server.js.

      'use strict';

const express = require('express');
const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync("tls.key"),
  cert: fs.readFileSync("tls.crt")
};

// Constants
const PORT = 9443;
const HOST = '0.0.0.0';

// App
const app = express();
app.get('/', (req, res) => {
  res.send('Hello world\n');
});

https.createServer(options, app).listen(PORT);

    7. Créez un fichier package.json dans le même répertoire que server.js. Exemple :

      {
  "name": "helloworld",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.16.4",
    "fs": "0.0.1-security",
    "https": "^1.0.0"
  }
}

    8. Exécutez npm install pour obtenir les dépendances.

    9. Créez un fichier Dockerfile dans le même répertoire que server.js, où WORKDIR correspond au chemin d'accès à la racine de votre application Node.js :

      FROM node:8-alpine
WORKDIR path-to-your-node-app
COPY package*.json ./

RUN npm install
COPY . .
EXPOSE 9443
CMD [ "npm", "start" ]

    10. Compilez l'image Docker :

      docker build -t helloworld .

    11. Démarrez l'exemple d'application :

      docker run -P -p 9443:9443 --name helloworld helloworld

    3. Créer des entités sur Apigee Edge

    1. Créez un proxy compatible avec Edge Microgateway avec les paramètres suivants. Pour en savoir plus, consultez Créer un proxy d'API compatible avec Edge Microgateway sur Edge.

      • Nom du proxy : edgemicro_local
      • Révision : 1
      • Chemin de base : /local
      • Cible : https://helloworld:9443

    2. Créez un produit d'API. Pour en savoir plus, consultez Créer un produit.

    3. Créez un développeur. Pour en savoir plus, consultez Créer un développeur.

    4. Créez une application de développeur. Pour en savoir plus, consultez Créer une application de développeur.

    4. Exécuter le conteneur

    1. Ouvrez le fichier de configuration Edge Micro dans un éditeur. Exemple :

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. Modifiez la stanza edgemicro comme suit. Notez que vous modifiez les attributs port et ssl :

      edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

    3. Exécutez la commande suivante pour encoder en base64 le fichier de configuration Edge Microgateway situé dans $HOME/.edgemicro :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      où your_org et your_env sont l'organisation et l'environnement que vous avez utilisés lorsque vous avez exécuté la commande edgemicro config.

      N'oubliez pas de placer des accents graves (`) autour de la commande. Exemple :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    4. Exécutez la commande suivante pour démarrer Edge Microgateway dans le conteneur Docker.

      chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

    5. Tester la configuration TLS

    1. Exécutez la commande cURL suivante pour tester la configuration. Remplacez le chemin de base que vous avez utilisé dans le proxy compatible avec la passerelle de microservices et la clé API obtenue à partir de l'application de développeur que vous avez créée sur Apigee Edge. Exemple :

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

      L'erreur suivante devrait s'afficher :

      ...
*  subject: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  start date: Dec 10 02:12:22 2018 GMT
*  expire date: Sep 29 02:12:22 2021 GMT
*  issuer: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 502 Bad Gateway
< Date: Wed, 12 Dec 2018 05:25:01 GMT
< Connection: keep-alive
< Content-Length: 93
<
* Connection #0 to host localhost left intact
{"message":"unable to verify the first certificate","code":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}

    2. Exécutez à nouveau Edge Microgateway, mais cette fois-ci, ajoutez la variable NODE_EXTRA_CA_CERTS.

      chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

    3. Exécutez la commande cURL suivante. Remplacez votre chemin de base et votre clé API comme précédemment. Exemple :

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

    4. Vérifiez le résultat. En cas de réussite, vous recevrez une réponse avec l'état HTTP 200 :

      ...
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 200 OK
< x-powered-by: Express
< content-type: text/html; charset=utf-8
< etag: W/"c-M6tWOb/Y57lesdjQuHeB1P/qTV0"
< date: Wed, 12 Dec 2018 05:49:28 GMT
< x-response-time: 421
< Connection: keep-alive
< Transfer-Encoding: chunked
<
Hello world

    Ajouter un plug-in personnalisé

    Vous pouvez ajouter de nouvelles fonctionnalités au microgateway en écrivant des plug-ins personnalisés. Les plug-ins personnalisés vous permettent d'interagir de manière programmatique avec les requêtes et les réponses qui transitent par la passerelle de microservices.

    Deux options s'offrent à vous pour déployer des plug-ins sur une instance Edge Microgateway exécutée dans un conteneur Docker :

    Le reste de cette section suppose que vous savez écrire et configurer des plug-ins pour une configuration Edge Microgateway standard. Si ce n'est pas le cas, consultez Développer des plug-ins personnalisés.

    Option A : Monter le répertoire des plug-ins sur un volume

    (Ajouté dans la version 2.5.27) La procédure d'ajout de plug-ins via un montage de volume est semblable à celle requise pour ajouter un plug-in personnalisé à Edge Microgateway. Lorsque vous exécutez le conteneur Docker, vous pouvez installer le répertoire des plug-ins sur le point d'installation du conteneur, qui est /opt/apigee/plugins. Vous spécifiez ensuite le répertoire de volume local dans le fichier de configuration Edge Microgateway.

    Les étapes suivantes montrent comment utiliser un point de montage Docker pour inclure des plug-ins personnalisés.

    1. Arrêtez Edge Microgateway :

      edgemicro stop

    2. Créez un répertoire pour vos plug-ins personnalisés. Par exemple, créez

      $HOME/edgemicro/custom/plugins

    3. Ajoutez le répertoire de plug-ins personnalisés au fichier de configuration Edge Microgateway. Exemple :

        plugins:
    dir: $HOME/edgemicro/custom/plugins
    sequence:
      - oauth
      - response-uppercase
  ````

    4. Écrivez et testez votre plug-in en suivant les instructions de la section Écrire un plug-in simple. Veillez à placer le code de votre plug-in dans la structure de répertoire appropriée. Exemple :

      custom
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

    5. Exécutez le conteneur Docker avec une commande semblable à la suivante, où vous utilisez l'option -v pour monter le répertoire des plug-ins sur le volume Docker. Dans l'exemple de commande suivant, le répertoire des plug-ins $HOME/edgemicro/custom/plugins (où se trouve le plug-in personnalisé) est mappé au point d'installation du conteneur /opt/apigee/plugins :

      chown -R 100:101 ~/.edgemicro/ \
docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-v $HOME/edgemicro/custom/plugins:/opt/apigee/plugins \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=jdoe \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=39c4b561100cd7f258768d1072f3e1d7c17b5f36a18fe89972bb5c9ce7e58fb \
-e EDGEMICRO_SECRET=f5f9e239a38b4e6cc99c2aa067716a84aebdcff9580a7925fc500e402b1a5fa \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL gcr.io/apigee-microgateway/edgemicro:latest

    6. Appelez votre API pour tester le plug-in.

    Pour en savoir plus, consultez VOLUME [systèmes de fichiers partagés].

    Option B : Intégrer les plug-ins au conteneur

    Dans cette option, vous intégrez les plug-ins à votre conteneur.

    1. Empaqueter vos plug-ins

    1. Écrivez et testez votre plug-in en suivant les instructions de la section Écrire un plug-in simple.

    2. Placez le code de votre plug-in dans la structure de répertoire appropriée. Les répertoires de plug-ins doivent respecter une structure définie. L'exemple suivant montre la structure à suivre, où response-uppercase et request-headers sont les noms des dossiers contenant le code du plug-in personnalisé (ces noms ne sont que des exemples, vos noms de dossiers peuvent être différents) :

      plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

    3. cd vers le dossier plugin.

    4. Dans le dossier plugin, compressez l'intégralité du dossier plugins :

      zip -r plugins.zip plugins/

    2. Créer une image Docker

    Créez ensuite un fichier Dockerfile pour ajouter le code de votre plug-in à une image Edge Microgateway.

    1. Dans le même répertoire que le fichier ZIP, créez un fichier nommé Dockerfile.

    2. Ajoutez le code suivant à Dockerfile et enregistrez le fichier :

      USER root
RUN apk update && \
    apk upgrade && \
    apk add zipapk add zip && \
    mkdir /opt/apigee/customplugins && \
    chown apigee:apigee /opt/apigee/customplugins
COPY plugins.zip /opt/apigee/customplugins
RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins"
EXPOSE 8000
EXPOSE 8443
USER apigee
ENTRYPOINT ["entrypoint"]

    3. Créez une image Docker Edge Microgateway avec vos plug-ins :

      docker build -t image-name .

      Exemple :

      docker build -t edgemicroplugins .

    3. Mettre à jour la configuration d'Edge Microgateway

    Maintenant que les plug-ins sont empaquetés, vous devez les ajouter au fichier de configuration Edge Microgateway.

    1. Ouvrez le fichier de configuration Edge Microgateway dans un éditeur :

      $HOME/.edgemicro/org-env-config.yaml

      Exemple :

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. Ajoutez le répertoire de plug-ins au fichier de configuration. Dans l'exemple suivant, l'attribut dir spécifie l'emplacement du code du plug-in (que vous avez spécifié dans le fichier Dockerfile). Vous devez également spécifier le nom du répertoire de plug-ins, qui est response-uppercase dans l'exemple ci-dessous. 

      edgemicro:
  ...
  plugins:
    dir: /opt/apigee/plugins
    sequence:
      - oauth
      - response-uppercase

    4. Démarrer la passerelle de microservices

    Enfin, vous devez démarrer la micro-passerelle dans le conteneur.

    1. Exécutez la commande suivante pour encoder en base64 le fichier de configuration Edge Microgateway situé dans $HOME/.edgemicro :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

      où your_org et your_env sont l'organisation et l'environnement que vous avez utilisés lorsque vous avez exécuté la commande edgemicro config.

      N'oubliez pas de placer des accents graves (`) autour de la commande. Exemple :

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    2. Exécutez Edge Microgateway en tant que conteneur. La commande définit plusieurs variables d'environnement utilisées par l'environnement d'exécution du conteneur pour démarrer Edge Microgateway :

      docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins image_name

      Exemple :

      docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins edgemicroplugins

    3. Appelez votre API pour tester le plug-in :

      Testez l'exécution du code du plug-in en appelant votre API et en vérifiant que le résultat est celui attendu :

      curl -i http://localhost:8000/hello -H "x-api-key:apikey"

      Par exemple, le plug-in response-uppercase peut renvoyer une réponse comme celle-ci :

      curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
  HELLO, WORLD!