Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Questo argomento spiega come eseguire Edge Microgateway in un container Docker. I passaggi descritti in questo argomento presuppongono una conoscenza di base di Docker, comandi Docker e configurazione e impostazione di Edge Microgateway. Per ulteriori informazioni, consulta la documentazione per Docker ed Edge Microgateway.
Prerequisiti
Prima di eseguire Edge Microgateway in un container Docker, devi eseguire le seguenti attività:
Configura Edge Microgateway per la tua organizzazione/ambiente Apigee:
edgemicro configure -o your_org -e your_env -u your_username
Per maggiori dettagli sulla configurazione, consulta la Parte 1: configurare Edge Microgateway.
Dopo aver eseguito i passaggi di configurazione, individua il file di configurazione. La posizione predefinita è questa:
$HOME/.edgemicro/your_org-your_env-config.yaml
dove
your_org
eyour_env
sono l'organizzazione e l'ambiente che hai utilizzato quando hai eseguito il comandoedgemicro config
. Avrai bisogno di questo file quando avvii Edge Microgateway in un container Docker.Assicurati di avere la chiave e le credenziali 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 proxy API autenticate. Queste entità includono un proxy compatibile con Edge Microgateway, un prodotto API, uno sviluppatore e un'app per sviluppatori. Per istruzioni complete, consulta Creare entità su Apigee Edge.
Esegui Edge Micro come container Docker
Scarica l'immagine Docker per Edge Microgateway:
docker pull gcr.io/apigee-microgateway/edgemicro:latest
Prima di procedere con i passaggi successivi, assicurati di aver eseguito tutti i passaggi della sezione Prerequisiti.
Esegui questo comando per codificare in base64 il file di configurazione Edge Microgateway posizionato in
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
dove
your_org
eyour_env
sono l'organizzazione e l'ambiente utilizzati quando hai eseguito il comandoedgemicro config
.Ricordati di inserire il segno di apice (`) intorno al comando. Ad esempio:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Esegui Edge Microgateway come container. Il comando imposta diverse variabili di ambiente utilizzate dal runtime del 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 per l'esecuzione di Docker. -p
Mappa esplicitamente una singola porta o un intervallo di porte. Vedi anche Riferimento per l'esecuzione di Docker. -d
Esegui in modalità separata. Vedi anche Riferimento per l'esecuzione di Docker. -v, -- volume
Specifica un montaggio del volume. Tieni presente che se configuri Edge Microgateway per l'utilizzo di TLS nel container Docker, devi esporre la porta 8443 se monta la directory del file di log. Vedi anche VOLUME [file system condivisi]. 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
eedgemicro.pid
. Non puoi modificare la radice del nome fileedgemicro
. Il valore predefinito è 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 è stata restituita durante la configurazione di Edge Microgateway. EDGEMICRO_SECRET
Il secret è stato restituito quando hai configurato Edge Microgateway. EDGEMICRO_CONFIG
Una variabile contenente il file di configurazione Edge Microgateway codificato in base64. LOG_CONSOLE_OUTPUT_TO_FILE
(Booleano) Consente di specificare dove deve essere inviato l'output del log. Vedi Specifica delle 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/edgemicroPer 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 lo stdout e l'output degli errori a un file che si trova nel container nella posizione:
${APIGEE_ROOT}/logs/edgemicro.log
.Per impedire l'invio delle informazioni di log a
edgemicro.log
, utilizza la variabileLOG_CONSOLE_OUTPUT_TO_FILE
quando esegui il container.La tabella seguente descrive il comportamento dell'output di log quando utilizzi
LOG_CONSOLE_OUTPUT_TO_FILE
conto_console
:to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=false
- Non verrà inviato nessun log al file di log di Edge Microgateway, come descritto in Gestire i file di log.
- I log non verranno inviati al file
edgemicro.log
.
to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=true
- Non verrà inviato nessun log al file di log di Edge Microgateway, come descritto in Gestire i 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 Gestire i 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 al container. Ad esempio, se il percorso base 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
Nella UI di Edge, vai all'app sviluppatore 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
come segue. Il valore della chiave utente che hai copiato dall'app sviluppatore è la chiave API. Per impostazione predefinita, Edge Microgateway prevede che tu passi la chiave in un'intestazione chiamatax-api-key
, come segue:curl -i http://localhost:8000/hello -H "x-api-key:apikey"
Ad esempio:
curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
Per saperne di più su come effettuare chiamate API autenticate tramite Edge Microgateway con chiavi API e token OAuth, consulta Parte 4: Secure Edge Microgateway.
Microgateway Stopping Edge
Utilizza il comando Docker seguente 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 in modo che utilizzi TLS per le richieste in entrata (direzione nord) e puoi configurare Edge Microgateway come client TLS per le richieste in uscita agli endpoint di destinazione (direzione verso 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 l'utilizzo dei certificati TLS, puoi rendere disponibili i file dei certificati in quel 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 il nome è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 considerata attendibile da Node.js
Se utilizzi un'autorità di certificazione (CA) non considerata attendibile per impostazione predefinita da Node.js (come nel caso di un certificato autofirmato), valuta l'utilizzo del 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 informazioni sull'utilizzo di questo parametro, vedi gli esempi Come configurare il TLS verso nord e Come configurare il TLS verso 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
Sebbene non sia consigliabile, in alcuni casi potresti voler disabilitare la convalida TLS per Edge Microgateway in esecuzione in un container. La funzionalità di disabilitazione di TLS non è incorporata nel container Docker Edge Microgateway per impostazione predefinita. Per eseguire 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.
Clona o scarica il repository di codice sorgente di Edge Microgateway da
https://github.com/apigee-internal/microgateway
.cd
alla directorymicrogateway/kubernetes/docker/edgemicro
nella directory del codice sorgente.Ad esempio:
cd $HOME/git/microgateway/kubernetes/docker/edgemicro
Apri il file
entrypoint.sh
e modifica il codice per accettare la variabile di ambienteNODE_TLS_REJECT_UNAUTHORIZED
. In seguito, quando eseguirai il contenitore, specificherai un valore per questa variabile.Crea il container Docker:
docker build -t edgemicro .
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 direzione nord (in arrivo) sul server Edge Microgateway. TLS in direzione nord consente ai client di utilizzare HTTPS quando effettuano chiamate API a Edge Microgateway. L'esempio seguente utilizza certificati autofirmati.
1. Passaggi di configurazione iniziali
- Individua il file
openssl.cnf
nel sistema. Ad esempio,/etc/ssl/openssl.cnf
. - Apri il file
opensssl.cnf
da modificare. Assicurati che
req_extensions
siano presenti nel file di configurazione. Ad esempio, il file deve contenere informazioni simili alle seguenti:[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
Aggiungi la stanza seguente 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
Esempio di file
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
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 sviluppatore. Inoltre, dovresti aver eseguito il comando
edgemicro configure
e ricevuto una chiave e un secret.
2. Genera certificati autofirmati
Quindi, genera i certificati e le chiavi necessari per stabilire TLS:
cd
alla directory$HOME/.edgemicro
.Crea il seguente script bash. Puoi assegnargli 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
Nel file bash, assicurati che il percorso al file
openssl.cnf
sia corretto.Esegui il file bash. Ti verranno chieste informazioni sul certificato. Assicurati di usare
localhost
come nome comune.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
Apri il file di configurazione Edge Micro in un editor. Ad esempio:
vi $HOME/.edgemicro/myorg-test-config.yaml
Modifica la stanza
edgemicro
come segue. Tieni presente che stai apportando modifiche agli attributiport
essl
: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: ...
Esegui questo comando per codificare in base64 il file di configurazione Edge Microgateway posizionato in
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
dove
your_org
eyour_env
sono l'organizzazione e l'ambiente utilizzati quando hai eseguito il comandoedgemicro config
.Ricordati di inserire il segno di apice (`) 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
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
Tieni presente i seguenti parametri utilizzati nel comando; sono diversi dal comando di base descritto in Eseguire Edge Micro come container Docker.
- Il campo
port
è impostato su8443
. - Un montaggio del volume viene utilizzato per montare i file della chiave e del certificato.
- La variabile
NODE_EXTRA_CA_CERTS
viene utilizzata per aggiungere una CA personalizzata (come necessario nel caso di certificati autofirmati).
- Il campo
5. Testare la configurazione TLS
Esegui questo comando cURL per testare la configurazione. Sostituisci il percorso base e la chiave API nel comando. L'esempio seguente presuppone che ti trovi nella directory in cui si trova
rootca.pem
e che il proxy che hai creato abbia il percorso base/hello
:curl -v https://localhost:8443/hello --cacert rootca.pem \ -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
L'output cURL dettagliato mostra ogni passaggio dell'handshake TLS. Se viene visualizzata 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 direzione sud
Questa sezione spiega come configurare una connessione TLS in direzione sud (in uscita) tra il server Edge Microgateway e un'applicazione di destinazione del backend. L'esempio seguente utilizza certificati autofirmati.
1. Passaggi iniziali di configurazione
- Individua il file
openssl.cnf
nel sistema. Ad esempio,/etc/ssl/openssl.cnf
. - Apri il file
opensssl.cnf
da modificare. Assicurati che
req_extensions
siano presenti nel file di configurazione. Ad esempio, il file deve contenere informazioni simili alle seguenti:[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
Aggiungi la stanza seguente 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
Esempio di file
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
Esegui il comando
edgemicro configure
:edgemicro configure -o your_org -e your_env -u your_username
Per maggiori dettagli sulla configurazione, consulta la Parte 1: configurare Edge Microgateway.
Copia la chiave e le credenziali del secret restituite da
edgemicro configure
. Questi valori saranno necessari 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
cd
alla directory.edgemicro
.Crea il seguente script bash. Puoi assegnargli 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
Nel file bash, assicurati che il percorso al file
openssl.cnf
sia corretto.Esegui il file bash. Ti verranno chieste informazioni sul certificato. Assicurati di usare
hellworld
come nome comune.Verifica che siano stati creati i seguenti file:
rootca.key
rootca.pem
tls.key
tls.csr
rootca.srl
tls.crt
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);
Crea un file
package.json
nella stessa directory diserver.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" } }
Esegui
npm install
per ottenere le dipendenze.Crea un nuovo Dockerfile nella stessa directory di
server.js
, doveWORKDIR
è il percorso della directory principale dell'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" ]
Crea l'immagine Docker:
docker build -t helloworld .
Avvia l'app di esempio:
docker run -P -p 9443:9443 --name helloworld helloworld
3. Crea entità su Apigee Edge
Crea un proxy Edge Microgateway con queste impostazioni. Per maggiori informazioni, consulta Creare un proxy API Edge Microgateway-aware su Edge.
- Nome proxy:
edgemicro_local
- Revisione:
1
- Percorso di base:
/local
- Target:
https://helloworld:9443
- Nome proxy:
Creare un prodotto API. Per maggiori dettagli, vedi Creare un prodotto.
Crea uno sviluppatore. Per maggiori dettagli, vedi Creare uno sviluppatore.
Crea un'app sviluppatore. Per maggiori dettagli, consulta Creare un'app sviluppatore.
4. Esegui il container
Apri il file di configurazione Edge Micro in un editor. Ad esempio:
vi $HOME/.edgemicro/myorg-test-config.yaml
Modifica la stanza
edgemicro
come segue. Tieni presente che stai apportando modifiche agli attributiport
essl
: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: ...
Esegui questo comando per codificare in base64 il file di configurazione Edge Microgateway che si trova in
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
dove
your_org
eyour_env
sono l'organizzazione e l'ambiente utilizzati quando hai eseguito il comandoedgemicro config
.Ricordati di inserire il segno di apice (`) intorno al comando. Ad esempio:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
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. Testare la configurazione TLS
Esegui questo comando cURL per testare la configurazione. Sostituisci il percorso base utilizzato nel proxy sensibile al microgateway e la chiave API ottenuta dall'app sviluppatore creata 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"}
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
Esegui il seguente comando cURL. Sostituisci percorso base e chiave API come prima. Ad esempio:
curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
Controlla l'output. Se l'operazione va a buon fine, riceverai una risposta dello 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
Aggiunta di un plug-in personalizzato
Puoi aggiungere nuove caratteristiche e capacità 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.
Per eseguire il deployment dei plug-in in un'istanza Edge Microgateway in esecuzione in un container Docker, hai due opzioni:
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 l'articolo Sviluppare plug-in personalizzati.
Opzione A: monta la directory dei plug-in su un volume
(Aggiunta nella v.2.5.27) I passaggi per aggiungere i plug-in tramite il 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 sistema locale (il volume) nel punto di montaggio del container, ovvero
/opt/apigee/plugins
. Dovrai quindi specificare la directory del volume locale nel file di configurazione Edge Microgateway.I passaggi seguenti illustrano come utilizzare un punto di montaggio Docker per includere plug-in personalizzati.
Interrompi microgateway Edge:
edgemicro stop
Crea una directory per i tuoi plug-in personalizzati. Ad esempio, crea
$HOME/edgemicro/custom/plugins
Aggiungi la directory del plug-in personalizzato al file di configurazione di Edge Microgateway. Ad esempio:
plugins: dir: $HOME/edgemicro/custom/plugins sequence: - oauth - response-uppercase ````
Scrivi e testa il plug-in in base alle istruzioni riportate in Scrivere un plug-in semplice. Assicurati di posizionare il codice plug-in nella struttura della directory corretta. Ad esempio:
custom | |-- plugins | |- response-uppercase | |- index.js | |- package.json |- request-headers | | - index.js | - package.json
Esegui il container Docker con un comando simile al seguente, dove utilizzerai l'opzione
-v
per montare la directory dei plug-in sul volume Docker. Nel comando di esempio seguente, 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
Chiama l'API per testare il plug-in.
Per ulteriori informazioni, consulta la sezione VOLUME [file system condivisi].
Opzione B: crea i plug-in nel container
In questa opzione, puoi creare i plug-in nel contenitore.
1. Crea un pacchetto di plug-in
Scrivi e testa il plug-in in base alle istruzioni riportate in Scrivere un plug-in semplice.
Inserisci il codice plug-in nella struttura della directory corretta. Le directory dei plug-in devono seguire una struttura prestabilita. L'esempio seguente mostra la struttura da seguire, dove
response-uppercase
erequest-headers
sono i nomi delle cartelle contenenti il codice 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
cd
nella cartellaplugin
.Nella cartella
plugin
, comprimi l'intera cartellaplugins
:zip -r plugins.zip plugins/
2. Crea un'immagine Docker
Quindi, crea un Dockerfile per aggiungere il codice plug-in a un'immagine Edge Microgateway.
- Nella stessa directory in cui si trova il file ZIP, crea un nuovo file denominato
Dockerfile
. 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"]
Crea una nuova immagine Docker 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 Edge Microgateway.
Apri il file di configurazione Edge Microgateway in un editor:
$HOME/.edgemicro/org-env-config.yaml
Ad esempio:
vi $HOME/.edgemicro/myorg-test-config.yaml
Aggiungi la directory del plug-in al file di configurazione. Nell'esempio seguente, l'attributo
dir
specifica la posizione del codice plug-in (specificata 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.
Esegui questo comando per codificare in base64 il file di configurazione Edge Microgateway posizionato in
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
dove
your_org
eyour_env
sono l'organizzazione e l'ambiente utilizzati quando hai eseguito il comandoedgemicro config
.Ricordati di inserire il segno di apice (`) intorno al comando. Ad esempio:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Esegui Edge Microgateway come container. Il comando imposta diverse variabili di ambiente utilizzate dal runtime del 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
Chiama l'API per testare il plug-in:
Verifica che il codice del plug-in venga eseguito chiamando la tua API e verificando 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 simile alla seguente:curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz" HELLO, WORLD!