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 SERVICE_NAME=edgemicro \
   --security-opt=no-new-privileges \
   --cap-drop=ALL \
   gcr.io/apigee-microgateway/edgemicro:latest

   Paramètres

   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.
   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.
   SERVICE_NAME	Si vous utilisez Kubernetes, ce paramètre est renseigné automatiquement. Sinon, vous pouvez définir la valeur de votre choix. Si vous ne spécifiez rien, le nom du service est défini sur default.
   DEBUG	Définissez la valeur sur * pour activer le débogage.
   HTTP_PROXY HTTPS_PROXY	Utilisez cette option lorsque Edge Microgateway s'exécute derrière un pare-feu et que la passerelle ne peut pas communiquer avec Apigee Edge. Pour en savoir plus, consultez Configurer Edge Microgateway derrière un pare-feu d'entreprise. Par exemple : HTTP_PROXY=http://10.203.0.1:5187/
   NO_PROXY	Liste de domaines séparés par une virgule vers lesquels Edge Microgateway ne doit pas rediriger le trafic. Pour en savoir plus, consultez Configurer Edge Microgateway derrière un pare-feu d'entreprise. Par exemple : localhost,127.0.0.1,localaddress,.localdomain.com
   NODE_EXTRA_CA_CERTS	(Facultatif) Utilisez ce paramètre si vous utilisez une autorité de certification qui n'est pas approuvée par défaut par Node.js. Définissez la valeur de ce paramètre sur le chemin d'accès à un fichier contenant un ou plusieurs certificats approuvés au format PEM. Pour en savoir plus, consultez Certificats TLS.
   --security-opt	(Facultatif) Définit les options de sécurité Docker souhaitées. Consultez la section Configuration de la sécurité dans la documentation Docker.
   --cap-drop	(Facultatif) Définit des limites sur les capacités Linux autorisées dans le conteneur. Consultez Droits d'exécution et capacités Linux dans la documentation Docker.

   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

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

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 Micro 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 :

• Option A : Installer le répertoire des plug-ins sur un volume
• Option B : Intégrer les plug-ins au conteneur

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!