Utilizzo di Docker per Edge Microgateway

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Questo argomento spiega come eseguire Edge Microgateway in un container Docker. I passaggi descritti in questo argomento presuppongono una conoscenza di base di Docker, dei comandi Docker e della configurazione di Edge Microgateway. Per maggiori informazioni, consulta la documentazione di Docker e di Edge Microgateway.

Prerequisiti

Prima di eseguire Edge Microgateway in un container Docker, devi eseguire le seguenti operazioni:

  • Configura Edge Microgateway per la tua organizzazione/il tuo ambiente Apigee:

    edgemicro configure -o your_org -e your_env -u your_username

    Per maggiori dettagli sulla configurazione, vedi Parte 1: configura Edge Microgateway.

  • Dopo aver eseguito i passaggi di configurazione, individua il file di configurazione. La località predefinita è:

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

    dove your_org e your_env sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comando edgemicro config. Avrai bisogno di questo file quando avvii Edge Microgateway in un container Docker.

  • Assicurati di avere le credenziali della chiave e del secret restituite quando hai eseguito il comando edgemicro config. Ad esempio:

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

  • Prima di avviare Edge Microgateway in un container Docker, devi creare (o aver creato) le entità Apigee Edge necessarie per effettuare chiamate autenticate ai proxy API. Queste entità includono un proxy compatibile con Edge Microgateway, un prodotto API, uno sviluppatore e un'app per sviluppatori. Per istruzioni complete, vedi Creare entità su Apigee Edge.

Esegui Edge Micro come container Docker

  1. Scarica l'immagine Docker per Edge Microgateway:

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

  2. Prima di procedere con i passaggi successivi, assicurati di aver eseguito tutti i passaggi della sezione Prerequisiti.

  3. Esegui questo comando per codificare in base64 il file di configurazione di Edge Microgateway che si trova in $HOME/.edgemicro:

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

    dove your_org e your_env sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comando edgemicro config.

    Ricordati di inserire gli apici inversi (`) intorno al comando. Ad esempio:

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

  4. Esegui Edge Microgateway come container. Il comando imposta diverse variabili di ambiente utilizzate dal runtime container per avviare 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

    Parametri

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

    Parametro Descrizione
    -P Pubblica tutte le porte esposte sull'host. Vedi anche Riferimento di docker run.
    -p Mappa esplicitamente una singola porta o un intervallo di porte. Vedi anche Riferimento di docker run.
    -d Esegui in modalità detached. Vedi anche Riferimento di docker run.
    -v, -- volume Specifica un montaggio del volume. Tieni presente che se configuri Edge Microgateway per utilizzare TLS nel container Docker, devi esporre la porta 8443 se monti la directory dei file di log. Vedi anche VOLUME [shared filesystems]. Vedi anche Utilizzo di TLS nel container Docker.
    -w, -- workdir (Facoltativo) Specifica il percorso della directory in cui devono essere creati i file edgemicro.sock e edgemicro.pid. Non puoi modificare la radice del nome file edgemicro. Per impostazione predefinita, è il percorso della directory di lavoro corrente.

    Esempio: 

    docker run -P -p 8000:8000 -d -w /tmp --name edgemicro 
    
...
    EDGEMICRO_ORG Il nome dell'organizzazione Apigee che hai utilizzato per configurare Edge Microgateway.
    EDGEMICRO_ENV Il nome dell'ambiente Apigee che hai utilizzato per configurare Edge Microgateway.
    EDGEMICRO_PROCESSES Il numero di processi da avviare.
    EDGEMICRO_KEY La chiave restituita durante la configurazione di Edge Microgateway.
    EDGEMICRO_SECRET Il secret restituito quando hai configurato Edge Microgateway.
    EDGEMICRO_CONFIG Una variabile contenente il file di configurazione di Edge Microgateway con codifica Base64.
    LOG_CONSOLE_OUTPUT_TO_FILE (Booleano) Consente di specificare dove viene inviato l'output del log. Consulta la sezione Specificare le opzioni del file di log.

    Ad esempio:

    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. Per verificare che il container sia in esecuzione:

      docker ps

      Dovresti vedere un output simile al seguente:

      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

    Specificare le opzioni di output del file di log

    Il parametro di configurazione di Edge Microgateway to_console ti consente di scegliere di inviare le informazioni di log all'output standard anziché a un file di log. Se segui i passaggi per eseguire Edge Microgateway in un container Docker, il container reindirizza per impostazione predefinita l'output stdout e degli errori a un file che si trova nel container nella posizione: ${APIGEE_ROOT}/logs/edgemicro.log.

    Per impedire l'invio di informazioni di log a edgemicro.log, utilizza la variabile LOG_CONSOLE_OUTPUT_TO_FILE quando esegui il contenitore.

    La seguente tabella descrive il comportamento dell'output dei log quando utilizzi LOG_CONSOLE_OUTPUT_TO_FILE con to_console:

    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=false

    • Nessun log verrà inviato al file di log di Edge Microgateway, come descritto in Gestione dei file di log.
    • I log non verranno inviati al file edgemicro.log.
    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • Nessun log verrà inviato al file di log di Edge Microgateway, come descritto in Gestione dei file di log.
    • I log verranno inviati al file edgemicro.log.
    to_console: false

    LOG_CONSOLE_OUTPUT_TO_FILE=true

    • I log verranno inviati al file di log di Edge Microgateway, come descritto in Gestione dei file di log.
    • I log verranno inviati al file edgemicro.log.

    Test di una chiamata API

    Dopo aver avviato Edge Microgateway nel container, puoi effettuare chiamate API. Ad esempio, se il basepath della tua API è /hello:

    http://localhost:8000/hello

    Esempio di output:

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

    Se vedi questa risposta, significa che Edge Microgateway ha gestito correttamente la chiamata API. Tuttavia, per impostazione predefinita, Edge Microgateway richiede una chiave API per l'autenticazione. Nella sezione successiva, testerai l'API con una chiave API valida.

    Testare un'API con una chiave API valida

    Nell'interfaccia utente Edge, vai all'app per sviluppatori che hai creato in precedenza. Nella pagina App sviluppatore, mostra la chiave utente e copiala. Questo valore è la chiave API. Utilizzerai questa chiave per effettuare chiamate API autenticate.

    Chiama l'API con l'intestazione x-api-key nel seguente modo. Il valore della chiave consumer che hai copiato dall'app per sviluppatori è la chiave API. Per impostazione predefinita, Edge Microgateway si aspetta che tu passi la chiave in un'intestazione chiamata x-api-key, in questo modo:

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

    Ad esempio:

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

    Se vuoi scoprire di più su come effettuare chiamate API autenticate tramite Edge Microgateway con chiavi API e token OAuth, consulta la Parte 4: Proteggere Edge Microgateway.

    Arresto di Edge Microgateway

    Utilizza il seguente comando Docker per arrestare Edge Microgateway:

    docker stop edgemicro

    Riavvio di Edge Microgateway

    Dopo aver arrestato Edge Microgateway, puoi riavviarlo con questo comando Docker:

    docker start edgemicro

    Utilizzo di TLS nel container Docker

    Questa sezione spiega come configurare TLS per Edge Microgateway in esecuzione in un container Docker. Puoi configurare il server Edge Microgateway per utilizzare TLS per le richieste in entrata (direzione nord) e puoi configurare Edge Microgateway in modo che sia un client TLS per le richieste in uscita agli endpoint di destinazione (direzione sud).

    Dove inserire i file dei certificati

    Il container Docker che esegue Edge Microgateway ha un punto di montaggio su /opt/apigee/.edgemicro. Quando configuri Edge Microgateway per utilizzare i certificati TLS, puoi rendere disponibili i file dei certificati nel punto di montaggio e farvi riferimento nel file di configurazione di Edge Microgateway. Questo file di configurazione si trova in genere nella directory $HOME/.edgemicro e si chiama your_org-your_env-config.yaml. Ad esempio:

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

    Utilizzo di una CA non attendibile da Node.js

    Se utilizzi un'autorità di certificazione (CA) non attendibile per impostazione predefinita da Node.js (come nel caso di un certificato autofirmato), valuta la possibilità di utilizzare il parametro NODE_EXTRA_CA_CERTS quando esegui il container.

    Imposta questo parametro sul percorso di un file contenente uno o più certificati attendibili in formato PEM. Per vedere come viene utilizzato questo parametro, consulta gli esempi Come configurare TLS in direzione nord e Come configurare TLS in direzione sud.

    Ad esempio:

    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

    Vedi anche Eseguire Edge Micro come container Docker.

    Disattivazione della convalida TLS

    Anche se non è consigliabile, in alcuni casi potresti voler disattivare la convalida TLS per Edge Microgateway in esecuzione in un container. La funzionalità per disattivare TLS non è integrata nel container Docker di Edge Microgateway per impostazione predefinita. Per completare l'attività, devi creare un'immagine Docker personalizzata per Edge Microgateway. Di seguito sono riportate le istruzioni generali per creare l'immagine personalizzata e disattivare la convalida TLS.

    1. Clona o scarica il repository di codice sorgente di Edge Microgateway da https://github.com/apigee-internal/microgateway.

    2. cd alla directory microgateway/kubernetes/docker/edgemicro nella directory del codice sorgente.

      Ad esempio:

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

    3. Apri il file entrypoint.sh e modifica il codice per accettare la variabile di ambiente NODE_TLS_REJECT_UNAUTHORIZED. In un secondo momento, quando esegui il contenitore, specificherai un valore per questa variabile.

    4. Crea il container Docker:

      docker build -t edgemicro .

    5. Quando esegui il container, specifica l'opzione -e NODE_TLS_REJECT_UNAUTHORIZED = 1. Ad esempio:

    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

    Esempio: come configurare TLS in direzione nord

    Questa sezione spiega come configurare una connessione TLS in uscita (in entrata) sul server Edge Microgateway. TLS in uscita consente ai client di utilizzare HTTPS quando effettuano chiamate API a Edge Microgateway. L'esempio riportato di seguito utilizza certificati autofirmati.

    1. Passaggi di configurazione iniziali

    1. Individua il file openssl.cnf sul tuo sistema. Ad esempio, /etc/ssl/openssl.cnf.
    2. Apri il file opensssl.cnf per modificarlo.

    3. Assicurati che req_extensions siano presenti nel file di configurazione. Ad esempio, nel file dovresti trovare informazioni simili a queste:

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

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

    4. Aggiungi la seguente sezione a openssl.cnf per generare gli attributi SNI corretti:

      [ 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

      File opensssl.cnf di esempio:

      [ 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. Segui i passaggi indicati nella sezione Prerequisiti per inizializzare e configurare Edge Microgateway, se non l'hai ancora fatto. Al termine, dovresti aver creato un proxy compatibile con Edge Microgateway, un prodotto API, uno sviluppatore e un'app per sviluppatori. Inoltre, dovresti aver eseguito il comando edgemicro configure e aver ricevuto una chiave e un segreto.

    2. Generare certificati autofirmati

    Successivamente, genera i certificati e le chiavi necessari per stabilire TLS:

    1. cd alla directory $HOME/.edgemicro.

    2. Crea il seguente script bash. Puoi assegnare il nome che preferisci. Ad esempio 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. Nel file bash, assicurati che il percorso del file openssl.cnf sia corretto.

    4. Esegui il file bash. Ti verranno richieste le informazioni sul certificato. Assicurati di utilizzare localhost per il nome comune.

    5. Verifica che siano stati creati i seguenti file:

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

    3. Modifica il file di configurazione di Edge Microgateway

    1. Apri il file di configurazione di Edge Micro in un editor. Ad esempio:

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

    2. Modifica la sezione edgemicro nel seguente modo. Tieni presente che stai apportando modifiche agli attributi port e 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. Esegui questo comando per codificare in base64 il file di configurazione di Edge Microgateway che si trova in $HOME/.edgemicro:

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

      dove your_org e your_env sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comando edgemicro config.

      Ricordati di inserire gli apici inversi (`) intorno al comando. Ad esempio:

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

    Vedi anche Eseguire Edge Micro come container Docker.

    4. Esegui il container

    1. Esegui questo comando per eseguire il container Docker con 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. Prendi nota dei seguenti parametri utilizzati nel comando, che differiscono dal comando di base descritto in Esegui Edge Micro come container Docker.

      • port è impostato su 8443.
      • Un montaggio del volume viene utilizzato per montare i file di chiavi e certificati.
      • La variabile NODE_EXTRA_CA_CERTS viene utilizzata per aggiungere una CA personalizzata (se necessario nel caso di certificati autofirmati).

    5. Testa la configurazione TLS

    1. Esegui il seguente comando cURL per testare la configurazione. Sostituisci il percorso di base e la chiave API nel comando. L'esempio seguente presuppone che tu ti trovi nella directory in cui si trova rootca.pem e che il proxy che hai creato abbia il basepath /hello:

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

    2. L'output dettagliato di cURL mostra ogni passaggio dell'handshake TLS. Se visualizzi una risposta HTTP 200, la configurazione è riuscita:

      *   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!

    Esempio: come configurare TLS in uscita

    Questa sezione spiega come configurare una connessione TLS in uscita tra il server Edge Microgateway e un'applicazione di destinazione di backend. L'esempio riportato di seguito utilizza certificati autofirmati.

    1. Passaggi di configurazione iniziali

    1. Individua il file openssl.cnf sul tuo sistema. Ad esempio, /etc/ssl/openssl.cnf.
    2. Apri il file opensssl.cnf per modificarlo.

    3. Assicurati che req_extensions siano presenti nel file di configurazione. Ad esempio, nel file dovresti trovare informazioni simili a queste:

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

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

    4. Aggiungi la seguente sezione a openssl.cnf per generare gli attributi SNI corretti:

      [ 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

      File opensssl.cnf di esempio:

      [ 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. Esegui il comando edgemicro configure:

      edgemicro configure -o your_org -e your_env -u your_username

      Per maggiori dettagli sulla configurazione, vedi Parte 1: configura Edge Microgateway.

    6. Copia le credenziali della chiave e del secret restituite da edgemicro configure. Avrai bisogno di questi valori per eseguire il container. Ad esempio:

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

    2. Crea un'applicazione di destinazione Node.js

    1. cd alla directory .edgemicro.

    2. Crea il seguente script bash. Puoi assegnare il nome che preferisci. Ad esempio 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. Nel file bash, assicurati che il percorso del file openssl.cnf sia corretto.

    4. Esegui il file bash. Ti verranno richieste le informazioni sul certificato. Assicurati di utilizzare hellworld per il nome comune.

    5. Verifica che siano stati creati i seguenti file:

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

    6. Crea un nuovo file denominato 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. Crea un file package.json nella stessa directory di server.js. Ad esempio:

      {
  "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. Esegui npm install per ottenere le dipendenze.

    9. Crea un nuovo Dockerfile nella stessa directory di server.js, dove WORKDIR è il percorso della radice della tua app 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. Crea l'immagine Docker:

      docker build -t helloworld .

    11. Avvia l'app di esempio:

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

    3. Crea entità su Apigee Edge

    1. Crea un proxy compatibile con Edge Microgateway con queste impostazioni. Per saperne di più, vedi Creare un proxy API compatibile con Edge Microgateway su Edge.

      • Nome proxy: edgemicro_local
      • Revisione: 1
      • Basepath: /local
      • Target: https://helloworld:9443

    2. Crea un prodotto API. Per maggiori dettagli, consulta Creare un prodotto.

    3. Crea uno sviluppatore. Per maggiori dettagli, vedi Creare uno sviluppatore.

    4. Crea un'app sviluppatore. Per i dettagli, vedi Creare un'app sviluppatore.

    4. Esegui il container

    1. Apri il file di configurazione di Edge Micro in un editor. Ad esempio:

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

    2. Modifica la sezione edgemicro nel seguente modo. Tieni presente che stai apportando modifiche agli attributi port e 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. Esegui il comando seguente per codificare in base64 il file di configurazione di Edge Microgateway che si trova in $HOME/.edgemicro:

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

      dove your_org e your_env sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comando edgemicro config.

      Ricordati di inserire gli apici inversi (`) intorno al comando. Ad esempio:

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

    4. Esegui questo comando per avviare Edge Microgateway nel container 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. Testa la configurazione TLS

    1. Esegui il seguente comando cURL per testare la configurazione. Sostituisci il percorso di base che hai utilizzato nel proxy compatibile con il microgateway e la chiave API ottenuta dall'app per sviluppatori che hai creato su Apigee Edge. Ad esempio:

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

      Dovresti visualizzare questo errore:

      ...
*  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. Esegui di nuovo Edge Microgateway, ma questa volta aggiungi la variabile 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. Esegui questo comando cURL. Sostituisci il percorso di base e la chiave API come prima. Ad esempio:

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

    4. Controlla l'output. In caso di esito positivo, riceverai una risposta con stato 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

    Aggiungere un plug-in personalizzato

    Puoi aggiungere nuove funzionalità al microgateway scrivendo plug-in personalizzati. I plug-in personalizzati ti consentono di interagire in modo programmatico con le richieste e le risposte che passano attraverso il microgateway.

    Hai due opzioni per il deployment dei plug-in in un'istanza di Edge Microgateway in esecuzione in un container Docker:

    Il resto di questa sezione presuppone che tu abbia familiarità con la scrittura e la configurazione dei plug-in per una configurazione standard di Edge Microgateway. In caso contrario, consulta Sviluppare plug-in personalizzati.

    Opzione A: monta la directory dei plug-in su un volume

    (Aggiunto nella versione 2.5.27) I passaggi per aggiungere plug-in tramite un montaggio del volume sono simili a quelli necessari per aggiungere qualsiasi plug-in personalizzato a Edge Microgateway. Quando esegui il container Docker, puoi montare la directory dei plug-in sul tuo sistema locale (il volume) sul punto di montaggio del container, ovvero /opt/apigee/plugins. Quindi, specifica la directory del volume locale nel file di configurazione di Edge Microgateway.

    I passaggi seguenti illustrano come utilizzare un punto di montaggio Docker per includere plug-in personalizzati.

    1. Arresta Edge Microgateway:

      edgemicro stop

    2. Crea una directory per i tuoi plug-in personalizzati. Ad esempio, crea

      $HOME/edgemicro/custom/plugins

    3. Aggiungi la directory dei plug-in personalizzati al file di configurazione di Edge Microgateway. Ad esempio:

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

    4. Scrivi e testa il plug-in seguendo le indicazioni riportate in Scrivere un plug-in semplice. Assicurati di inserire il codice del plug-in nella struttura di directory corretta. Ad esempio:

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

    5. Esegui il container Docker con un comando simile al seguente, in cui utilizzi l'opzione -v per montare la directory dei plug-in sul volume Docker. Nel seguente comando di esempio, la directory dei plug-in $HOME/edgemicro/custom/plugins (dove si trova il plug-in personalizzato) è mappata al punto di montaggio del container /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. Chiama l'API per testare il plug-in.

    Per saperne di più, vedi VOLUME [file system condivisi].

    Opzione B: incorpora i plug-in nel container

    In questa opzione, crei i plug-in nel container.

    1. Pacchettizzare i plug-in

    1. Scrivi e testa il plug-in seguendo le indicazioni riportate in Scrivere un plug-in semplice.

    2. Inserisci il codice del plug-in nella struttura di directory corretta. Le directory dei plug-in devono seguire una struttura specifica. L'esempio seguente mostra la struttura da seguire, in cui response-uppercase e request-headers sono i nomi delle cartelle contenenti il codice del plug-in personalizzato (questi nomi sono solo esempi, i nomi delle cartelle potrebbero essere diversi):

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

    3. cd nella cartella plugin.

    4. Nella cartella plugin, comprimi l'intera cartella plugins:

      zip -r plugins.zip plugins/

    2. Crea un'immagine Docker

    Successivamente, crea un Dockerfile per aggiungere il codice del plug-in a un'immagine Edge Microgateway.

    1. Nella stessa directory in cui si trova il file ZIP, crea un nuovo file denominato Dockerfile.

    2. Aggiungi il seguente codice a Dockerfile e salva il file:

      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. Crea una nuova immagine Docker di Edge Microgateway con i tuoi plug-in:

      docker build -t image-name .

      Ad esempio:

      docker build -t edgemicroplugins .

    3. Aggiorna la configurazione di Edge Microgateway

    Ora che i plug-in sono pacchettizzati, devi aggiungerli al file di configurazione di Edge Microgateway.

    1. Apri il file di configurazione di Edge Microgateway in un editor:

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

      Ad esempio:

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

    2. Aggiungi la directory del plug-in al file di configurazione. Nell'esempio seguente, l'attributo dir specifica la posizione del codice del plug-in (che hai specificato nel Dockerfile). Devi anche specificare il nome della directory dei plug-in, che nell'esempio seguente è response-uppercase. 

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

    4. Avvia il microgateway

    Infine, devi avviare il microgateway nel container.

    1. Esegui questo comando per codificare in base64 il file di configurazione di Edge Microgateway che si trova in $HOME/.edgemicro:

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

      dove your_org e your_env sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comando edgemicro config.

      Ricordati di inserire gli apici inversi (`) intorno al comando. Ad esempio:

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

    2. Esegui Edge Microgateway come container. Il comando imposta diverse variabili di ambiente utilizzate dal runtime container per avviare 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

      Ad esempio:

      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. Chiama l'API per testare il plug-in:

      Verifica che il codice del plug-in venga eseguito chiamando l'API e controllando che l'output sia quello previsto:

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

      Ad esempio, il plug-in response-uppercase potrebbe restituire una risposta come questa:

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