Utiliser Docker pour Edge Microtation

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

Cet article explique comment exécuter Edge Microgateway dans un conteneur Docker. Les étapes abordées dans cet article supposent que vous possédez des connaissances de base sur la configuration de Docker, des commandes Docker et d'Edge Microgateway. Pour en savoir plus, consultez la documentation sur 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 plus d'informations sur la configuration, consultez la Partie 1: Configurer Edge Microgateway.

  • Une fois ces étapes de configuration effectuées, localisez le fichier de configuration. L'emplacement par défaut est le suivant:

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

    your_org et your_env sont l'organisation et l'environnement que vous avez utilisés lors de l'exécution de la commande edgemicro config. Vous en aurez besoin lorsque vous démarrerez Edge Microgateway dans un conteneur Docker.

  • Assurez-vous de disposer des identifiants de clé et de secret qui vous ont été renvoyés lors de l'exécution de 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 de proxy d'API authentifiés. 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 la section 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 suivi 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`

    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 guillemets obliques (`) 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 qui sont utilisées par l'environnement d'exécution du conteneur pour démarrer Edge Microgateway:

    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 le document de référence sur l'exécution de Docker.
    -p Mappez explicitement un seul port ou une seule plage de ports. Consultez également le document de référence sur l'exécution de Docker.
    -d Exécuter en mode dissocié. Consultez également le document de référence sur l'exécution de Docker.
    -v, --volume Spécifie l'installation d'un volume. Notez que si vous configurez Edge Microgateway pour utiliser TLS dans le conteneur Docker, vous devez exposer le port 8443 si vous installez le répertoire de fichiers journaux. Consultez également VOLUME [systèmes de fichiers partagés]. Consultez également la page 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 lors de la configuration d'Edge Microgateway.
    EDGEMICRO_SECRET Secret renvoyé lors de la configuration d'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 la définir comme vous le souhaitez. 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 plus d'informations, consultez la section 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 que Edge Microgateway ne doit pas utiliser comme proxy. Pour plus d'informations, consultez la section 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 employez 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 de confiance au format PEM. Pour en savoir plus, consultez la section 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 les limites des capacités Linux autorisées dans le conteneur. Consultez la section sur les droits d'exécution et capacités Linux dans la documentation Docker.

    Exemple :

    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

Après avoir démarré Edge Microgateway dans le conteneur, vous pouvez y effectuer 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 vous voyez cette réponse, cela signifie qu'Edge Microgateway a correctement géré l'appel d'API. Cependant, Edge Microgateway nécessite par défaut 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éveloppement que vous avez créée précédemment. Sur la page de l'application du 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 depuis l'application de développement est 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"

Si vous souhaitez en savoir plus sur les appels d'API authentifiés via Edge Microgateway à l'aide de clés API et de jetons OAuth, consultez la Partie 4: Secure Edge Microgateway.

Arrêt d'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 à l'aide de la commande Docker suivante:

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 de sorte qu'il utilise TLS pour les requêtes entrantes (direction nord). Vous pouvez également configurer Edge Microgateway en tant que client TLS pour les requêtes sortantes vers des points de terminaison cibles (direction sud).

Où placer les fichiers de certificat ?

Le conteneur Docker exécutant Edge Microgateway possède un point d'installation sur /opt/apigee/.edgemicro. Lorsque vous configurez Edge Microgateway pour utiliser des certificats TLS, vous pouvez rendre les fichiers de certificats disponibles sur ce point d'installation et vous y référer dans le fichier de configuration Edge Microgateway. Ce fichier de configuration se trouve généralement dans le répertoire $HOME/.edgemicro et s'appelle 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 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 de confiance au format PEM. Pour voir comment ce paramètre est utilisé, consultez les exemples Configurer le protocole TLS vers le nord et Configurer le protocole TLS de la limite sud.

Exemple :

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 la page 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 s'exécutant dans un conteneur. La fonctionnalité de désactivation du protocole TLS n'est pas intégrée par défaut au conteneur Docker d'Edge Microgateway. Pour accomplir cette tâche, 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 à partir de https://github.com/apigee-internal/microgateway.

  2. cd dans le répertoire microgateway/kubernetes/docker/edgemicro du répertoire du 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 indiquerez 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 :

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: Comment configurer une connexion TLS limitée au nord

Cette section explique comment configurer une connexion TLS de liaison nord (entrante) sur le serveur Edge Microgateway. Le protocole TLS de liaison nord 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 aux suivantes:

    [ req ]
    ...
    req_extensions          = v3_req
    ...
    
    [ v3_req ]
    extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
    
  4. Ajoutez le bloc suivant à openssl.cnf pour générer les attributs SNI appropriés:

    [ 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. Si vous ne l'avez pas déjà fait, suivez la procédure indiquée dans la section Conditions préalables pour initialiser et configurer Edge Microgateway. Une fois l'opération terminée, vous devez avoir créé un proxy compatible avec Edge Microgateway, un produit d'API, un développeur et une application de développement. En outre, vous devez avoir exécuté la commande edgemicro configure et reçu une clé et un code secret.

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

Générez ensuite 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 le nommer comme vous le souhaitez. 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é à saisir des informations sur le certificat. Veillez à utiliser localhost comme nom commun.

  5. Vérifiez que les fichiers suivants ont bien é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 le 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`

    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 guillemets obliques (`) autour de la commande. Exemple :

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

Consultez également la page 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:

    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 que les paramètres suivants utilisés dans la commande diffèrent de la commande de base décrite dans la section Exécuter Edge Micro en tant que conteneur Docker.

    • La valeur de port est définie sur 8443.
    • L'installation d'un volume permet d'installer les fichiers de clé et de certificat.
    • La variable NODE_EXTRA_CA_CERTS permet d'ajouter une autorité de certification 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 le chemin d'accès de base et la 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éé possède le chemin de base /hello:

    curl -v https://localhost:8443/hello --cacert rootca.pem \
    -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
    
  2. La sortie détaillée de cURL affiche chaque étape du handshake TLS. Si une réponse HTTP 200 s'affiche, cela signifie que 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 une liaison TLS limitée au sud

Cette section explique comment configurer une connexion TLS sortante au sud entre le serveur Edge Microgateway et une application cible 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 aux suivantes:

    [ req ]
    ...
    req_extensions          = v3_req
    ...
    
    [ v3_req ]
    extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
    
  4. Ajoutez le bloc suivant à openssl.cnf pour générer les attributs SNI appropriés:

    [ 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 plus d'informations sur la configuration, consultez la Partie 1: Configurer Edge Microgateway.

  6. Copiez les identifiants de clé et de secret qui ont été renvoyés par edgemicro configure. Vous en aurez besoin 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 le nommer comme vous le souhaitez. 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é à saisir des informations sur le certificat. Veillez à utiliser hellworld comme nom commun.

  5. Vérifiez que les fichiers suivants ont bien é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 Dockerfile dans le même répertoire que server.js, où WORKDIR est le 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. Créez l'image Docker:

    docker build -t helloworld . 
    
  11. Démarrez l'application exemple:

    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 ces paramètres. Pour plus d'informations, 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éer un produit API Pour plus d'informations, voir 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 le 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`

    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 guillemets obliques (`) 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.

    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 micro-passerelle et la clé API obtenue à partir de l'application de développement 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, ajoutez la variable NODE_EXTRA_CA_CERTS.

    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 le chemin d'accès de base et la 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 obtenez une réponse d'é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 à la micropasserelle en écrivant des plug-ins personnalisés. Les plug-ins personnalisés vous permettent d'interagir de manière automatisée avec les requêtes et les réponses qui transitent par la micropasserelle.

Vous disposez de deux options pour déployer des plug-ins sur une instance Edge Microgateway s'exécutant 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, reportez-vous à la section Développer des plug-ins personnalisés.

Option A: Installer le répertoire de plug-ins sur un volume

(Ajoutée dans la version 2.5.27) La procédure d'ajout de plug-ins via l'installation d'un 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 de plug-ins sur votre système local (le volume) sur le point d'installation du conteneur, à savoir /opt/apigee/plugins. Spécifiez ensuite le répertoire de volume local dans le fichier de configuration Edge Microgateway.

Les étapes suivantes montrent comment utiliser un point d'installation 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 du plug-in personnalisé 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 l'article Écrire un plug-in simple. Veillez à placer le code de votre plug-in dans la structure de répertoires appropriée. Exemple :

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

    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: Créer les plug-ins dans le conteneur

Avec cette option, vous créez les plug-ins dans votre conteneur.

1. Empaqueter vos plug-ins

  1. Écrivez et testez votre plug-in en suivant les instructions de l'article Écrire un plug-in simple.

  2. Placez le code de votre plug-in dans la structure de répertoires 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 du code de plug-in personnalisé (ces noms ne sont que des exemples, et les noms de vos dossiers peuvent être différents):

    plugin
      |
      |-- plugins
        |
        |- response-uppercase
        |     |- index.js
        |     |- package.json
        |- request-headers
        |     | - index.js
              | - package.json
    
  3. cd dans 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 Dockerfile pour ajouter le code de votre plug-in à une image Edge Microgateway.

  1. Dans le répertoire où se trouve 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 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 du plug-in 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 du plug-in, qui dans l'exemple ci-dessous est response-uppercase.

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

4. Démarrer la micropasserelle

Enfin, vous devez démarrer la micropasserelle 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`

    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 guillemets obliques (`) 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 qui sont 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 conforme aux attentes:

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

    Par exemple, le plug-in response-uppercase peut renvoyer une réponse de ce type:

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