Riferimento per le operazioni e la configurazione di Edge Microgateway

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

Edge Microgateway v. 2.5.x

Questo argomento spiega come gestire e configurare Edge Microgateway.

Esegui l'upgrade di Edge Microgateway se hai una connessione a internet

1. Esegui questo comando npm per eseguire l'upgrade all'ultima versione di Edge Microgateway:

   npm upgrade edgemicro -g

   Per eseguire l'upgrade a una versione specifica di Edge Microgateway, devi specificare il numero di versione nel comando di upgrade. Se non specifichi il numero di versione, verrà installata l'ultima versione. Ad esempio, per eseguire l'upgrade alla versione 2.5.26, utilizza il seguente comando:

   npm upgrade edgemicro@2.5.26 -g

2. Controlla il numero di versione. Ad esempio, se hai installato la versione 2.5.26:

   edgemicro --version
   current nodejs version is v8.9.0
   current edgemicro version is 2.5.26
       

3. Infine, esegui l'upgrade all'ultima versione del proxy edgemicro-auth:

   edgemicro upgradeauth -o org_name -e env_name -u username

Apportare modifiche alla configurazione

I file di configurazione che devi conoscere includono:

• File di configurazione di sistema predefinito
• File di configurazione predefinito per un'istanza Edge Microgateway appena inizializzata
• File di configurazione dinamico per le istanze in esecuzione

Questa sezione illustra questi file e ciò che devi sapere per modificarli.

File di configurazione di sistema predefinito

Quando installi Edge Microgateway, un file di configurazione di sistema predefinito viene inserito qui:

prefix/lib/node_modules/edgemicro/config/default.yaml

Dove prefix è la directory del prefisso npm. Consulta Dove è installato Edge Microgateway se non riesci a trovare questa directory.

Se modifichi il file di configurazione del sistema, devi reinizializzare, riconfigurare e riavviare Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

File di configurazione predefinito per le istanze di Edge Microgateway appena inizializzate

Quando esegui edgemicro init, il file di configurazione di sistema (descritto sopra), default.yaml, viene inserito nella directory ~/.edgemicro.

Se modifichi il file di configurazione in ~/.edgemicro, devi riconfigurare e riavviare Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

File di configurazione dinamico per le istanze in esecuzione

Quando esegui edgemicro configure [params], viene creato un file di configurazione dinamica in ~/.edgemicro. Il nome del file segue questo pattern: org-env-config.yaml, dove org e env sono i nomi dell'organizzazione e dell'ambiente Apigee Edge. Puoi utilizzare questo file per apportare modifiche alla configurazione e poi ricaricarle senza tempi di inattività. Ad esempio, se aggiungi e configuri un plug-in, puoi ricaricare la configurazione senza tempi di inattività, come spiegato di seguito.

Se Edge Microgateway è in esecuzione (opzione senza tempi di inattività):

1. Ricarica la configurazione di Edge Microgateway:

   edgemicro reload -o org_name -e env_name -k key -s secret

   Dove:

   • org_name è il nome della tua organizzazione Edge (devi essere un amministratore dell'organizzazione).
   • env_name è un ambiente della tua organizzazione (ad esempio "test" o "prod").
   • key è la chiave restituita in precedenza dal comando configure.
   • secret è la chiave restituita in precedenza dal comando configure.

   Ad esempio:

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

Se Edge Microgateway è stato arrestato:

1. Riavvia Edge Microgateway:

   edgemicro start -o org_name -e env_name -k key -s secret

   Dove:

   • org_name è il nome della tua organizzazione Edge (devi essere un amministratore dell'organizzazione).
   • env_name è un ambiente della tua organizzazione (ad esempio "test" o "prod").
   • key è la chiave restituita in precedenza dal comando configure.
   • secret è la chiave restituita in precedenza dal comando configure.

   Ad esempio:

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Ecco un file di configurazione di esempio. Per i dettagli sulle impostazioni del file di configurazione, consulta il riferimento alla configurazione di Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Imposta le variabili di ambiente

I comandi dell'interfaccia a riga di comando che richiedono valori per l'organizzazione e l'ambiente Edge, nonché la chiave e il secret necessari per avviare Edge Microgateway, possono essere archiviati in queste variabili di ambiente:

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

L'impostazione di queste variabili è facoltativa. Se le imposti, non devi specificare i relativi valori quando utilizzi l'interfaccia a riga di comando (CLI) per configurare e avviare Edge Microgateway.

Configurazione di SSL sul server Edge Microgateway

Puoi configurare il server Microgateway in modo che utilizzi SSL. Ad esempio, con SSL configurato, puoi chiamare le API tramite Edge Microgateway con il protocollo "https", in questo modo:

https://localhost:8000/myapi

Per configurare SSL sul server Microgateway, segui questi passaggi:

1. Genera o ottieni un certificato e una chiave SSL utilizzando l'utilità openssl o il metodo che preferisci.
2. Aggiungi l'attributo edgemicro:ssl al file di configurazione di Edge Microgateway. Per un elenco completo delle opzioni, consulta la tabella seguente. Ad esempio:
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Riavvia Edge Microgateway. Segui i passaggi descritti in Apportare modifiche alla configurazione a seconda del file di configurazione che hai modificato: il file predefinito o il file di configurazione di runtime.

Ecco un esempio della sezione edgemicro del file di configurazione, con SSL configurato:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Di seguito è riportato un elenco di tutte le opzioni del server supportate:

Utilizzo delle opzioni SSL/TLS client

Puoi configurare Edge Microgateway in modo che agisca come client TLS o SSL quando si connette agli endpoint di destinazione. Nel file di configurazione di Microgateway, utilizza l'elemento targets per impostare le opzioni SSL/TLS.

Questo esempio fornisce le impostazioni che verranno applicate a tutti gli host:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

In questo esempio, le impostazioni vengono applicate solo all'host specificato:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Ecco un esempio per TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Ecco un elenco di tutte le opzioni client supportate:

Personalizzazione del proxy edgemicro-auth

Per impostazione predefinita, Edge Microgateway utilizza un proxy di cui è stato eseguito il deployment su Apigee Edge per l'autenticazione OAuth2. Il deployment di questo proxy viene eseguito quando esegui edgemicro configure per la prima volta. Puoi modificare la configurazione predefinita di questo proxy per aggiungere il supporto per le rivendicazioni personalizzate a un token web JSON (JWT), configurare la scadenza dei token e generare token di aggiornamento. Per i dettagli, consulta la pagina edgemicro-auth su GitHub.

Utilizzo di un servizio di autenticazione personalizzato

Per impostazione predefinita, Edge Microgateway utilizza un proxy di cui è stato eseguito il deployment su Apigee Edge per l'autenticazione OAuth2. Il deployment di questo proxy viene eseguito quando esegui edgemicro configure per la prima volta. Per impostazione predefinita, l'URL di questo proxy è specificato nel file di configurazione di Edge Microgateway come segue:

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Se vuoi utilizzare il tuo servizio personalizzato per gestire l'autenticazione, modifica il valore authUri nel file di configurazione in modo che rimandi al tuo servizio. Ad esempio, potresti avere un servizio che utilizza LDAP per verificare l'identità.

Gestione dei file di log

Edge Microgateway registra le informazioni su ogni richiesta e risposta. I file di log forniscono informazioni utili per il debug e la risoluzione dei problemi.

Dove vengono archiviati i file di log

Per impostazione predefinita, i file di log vengono archiviati in /var/tmp.

Come modificare la directory predefinita dei file di log

La directory in cui sono archiviati i file di log è specificata nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Modifica il valore dir per specificare una directory dei file di log diversa.

Invia i log alla console

Puoi configurare il logging in modo che le informazioni di log vengano inviate all'output standard anziché a un file di log. Imposta il flag to_console su true come segue:

edgemicro:
  logging:
    to_console: true

Con questa impostazione, i log verranno inviati allo standard out. Al momento, non puoi inviare i log sia a stdout sia a un file di log.

Come impostare il livello di logging

Puoi impostare i seguenti livelli di log: info, warn ed error. Il livello info è consigliato. Registra tutte le richieste e le risposte API ed è l'impostazione predefinita.

Come modificare gli intervalli di registrazione

Puoi configurare questi intervalli nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

Gli attributi configurabili sono:

• stats_log_interval: (valore predefinito: 60) intervallo, in secondi, in cui il record delle statistiche viene scritto nel file di log dell'API.
• rotate_interval: (valore predefinito: 24) intervallo, in ore, in cui i file di log vengono ruotati. Ad esempio:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Best practice per la manutenzione dei file di log

Man mano che i dati dei file di log si accumulano nel tempo, Apigee consiglia di adottare le seguenti pratiche:

• Poiché i file di log possono diventare piuttosto grandi, assicurati che la directory dei file di log disponga di spazio sufficiente. Consulta le sezioni seguenti Dove vengono archiviati i file di log e Come modificare la directory predefinita dei file di log.
• Elimina o sposta i file di log in una directory di archiviazione separata almeno una volta alla settimana.
• Se la tua policy prevede l'eliminazione dei log, puoi utilizzare il comando dell'interfaccia a riga di comando edgemicro log -c per rimuovere (pulire) i log meno recenti.

Convenzione di denominazione dei file di log

Ogni istanza di Edge Microgateway genera tre tipi di file di log:

• api: registra tutte le richieste e le risposte che passano attraverso Edge Microgateway. In questo file vengono registrati anche i contatori (statistiche) e gli errori dell'API.
• err: registra tutto ciò che viene inviato a stderr.
• out: registra tutto ciò che viene inviato a stdout.

Questa è la convenzione di denominazione:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Ad esempio:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

Informazioni sui contenuti dei file di log

Aggiunta nella versione 2.3.3

Per impostazione predefinita, il servizio di logging omette il JSON dei proxy e dei prodotti scaricati e il token web JSON (JWT). Se vuoi restituire questi oggetti nei file di log, imposta DEBUG=* quando avvii Edge Microgateway. Ad esempio:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Contenuti del file di log "api"

Il file di log "api" contiene informazioni dettagliate sul flusso di richieste e risposte tramite Edge Microgateway. I file di log "api" sono denominati come segue:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Per ogni richiesta inviata a Edge Microgateway, nel file di log "api" vengono acquisiti quattro eventi:

• Richiesta in arrivo dal client
• Richiesta in uscita effettuata alla destinazione
• Risposta in entrata dal target
• Risposta in uscita al client

Ognuna di queste voci separate è rappresentata in una notazione abbreviata per contribuire a rendere i file di log più compatti. Ecco quattro voci di esempio che rappresentano ciascuno dei quattro eventi. Nel file di log, l'aspetto è il seguente (i numeri di riga sono solo a scopo di riferimento nel documento, non vengono visualizzati nel file di log).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Vediamoli uno alla volta:

1. Esempio di richiesta in entrata dal client:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651: timestamp Unix
• info: dipende dal contesto. Può essere info, warn o error, a seconda del livello di log. Può essere "stats" per un record di statistiche, "warn" per gli avvisi o "error" per gli errori.
• req: identifica l'evento. In questo caso, la richiesta proviene dal client.
• m: il verbo HTTP utilizzato nella richiesta.
• u: la parte dell'URL che segue il percorso di base.
• h: l'host e il numero di porta su cui Edge Microgateway è in ascolto.
• r: l'host e la porta remoti da cui ha avuto origine la richiesta del client.
• i: l'ID richiesta. Tutte e quattro le voci dell'evento condivideranno questo ID. A ogni richiesta viene assegnato un ID richiesta univoco. La correlazione dei record di log in base all'ID richiesta può fornire informazioni preziose sulla latenza della destinazione.
• d: la durata in millisecondi dalla ricezione della richiesta da parte di Edge Microgateway. Nell'esempio precedente, la risposta della destinazione per la richiesta 0 è stata ricevuta dopo 7 millisecondi (riga 3) e la risposta è stata inviata al client dopo altri 4 millisecondi (riga 4). In altre parole, la latenza totale della richiesta è stata di 11 millisecondi, di cui 7 millisecondi sono stati impiegati dalla destinazione e 4 millisecondi da Edge Microgateway stesso.

2. Esempio di richiesta in uscita inviata alla destinazione:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651: timestamp Unix
• info: dipende dal contesto. Può essere info, warn o error, a seconda del livello di log. Può essere "stats" per un record di statistiche, "warn" per gli avvisi o "error" per gli errori.
• treq: identifica l'evento. In questo caso, la richiesta di destinazione.
• m: il verbo HTTP utilizzato nella richiesta di destinazione.
• u: la parte dell'URL che segue il percorso di base.
• h: l'host e il numero di porta del target di backend.
• i: l'ID della voce di log. Tutte e quattro le voci dell'evento condivideranno questo ID.

3. Esempio di risposta in entrata dal target

1436403888672 info tres s=200, d=7, i=0

1436403888651: timestamp Unix

• info: dipende dal contesto. Può essere info, warn o error, a seconda del livello di log. Può essere "stats" per un record di statistiche, "warn" per gli avvisi o "error" per gli errori.
• tres: identifica l'evento. In questo caso, la risposta target.
• s: lo stato della risposta HTTP.
• d: la durata in millisecondi. Il tempo impiegato per la chiamata API dal target.
• i: l'ID della voce di log. Tutte e quattro le voci dell'evento condivideranno questo ID.

4. Esempio di risposta in uscita al client

1436403888676 info res s=200, d=11, i=0

1436403888651: timestamp Unix

• info: dipende dal contesto. Può essere info, warn o error, a seconda del livello di log. Può essere "stats" per un record di statistiche, "warn" per gli avvisi o "error" per gli errori.
• res: identifica l'evento. In questo caso, rispondi al client.
• s: lo stato della risposta HTTP.
• d: la durata in millisecondi. Questo è il tempo totale impiegato dalla chiamata API, incluso il tempo impiegato dall'API di destinazione e il tempo impiegato da Edge Microgateway stesso.
• i: l'ID della voce di log. Tutte e quattro le voci dell'evento condivideranno questo ID.

Pianificazione dei file di log

I file di log vengono ruotati in base all'intervallo specificato dall'attributo di configurazione rotate_interval. Le voci continueranno a essere aggiunte allo stesso file di log fino alla scadenza dell'intervallo di rotazione. Tuttavia, ogni volta che Edge Microgateway viene riavviato, riceve un nuovo UID e crea un nuovo set di file di log con questo UID. Consulta anche Best practice per la manutenzione dei file di log.

Messaggi di errore

Alcune voci di log conterranno messaggi di errore. Per identificare dove e perché si verificano gli errori, consulta il Riferimento errori di Edge Microgateway.

Riferimento alla configurazione di Edge Microgateway

Posizione del file di configurazione

Gli attributi di configurazione descritti in questa sezione si trovano nel file di configurazione di Edge Microgateway. Consulta anche Apportare modifiche alla configurazione.

Attributi edge_config

Queste impostazioni vengono utilizzate per configurare l'interazione tra l'istanza di Edge Microgateway e Apigee Edge.

• bootstrap: (valore predefinito: none) un URL che punta a un servizio specifico di Edge Microgateway in esecuzione su Apigee Edge. Edge Microgateway utilizza questo servizio per comunicare con Apigee Edge. Questo URL viene restituito quando esegui il comando per generare la coppia di chiavi pubblica/privata: edgemicro genkeys. Per maggiori dettagli, consulta Configurazione di Edge Microgateway.
• jwt_public_key: (predefinito: nessuno) un URL che punta al proxy Edge Microgateway di cui è stato eseguito il deployment su Apigee Edge. Questo proxy funge da endpoint di autenticazione per l'emissione di token di accesso firmati ai client. Questo URL viene restituito quando esegui il comando per il deployment del proxy: edgemicro configure. Per maggiori dettagli, consulta Configurazione di Edge Microgateway.

attributi edgemicro

Queste impostazioni configurano il processo di Edge Microgateway.

• port: (valore predefinito: 8000) il numero di porta su cui il processo Edge Microgateway rimane in ascolto.
• max_connections: (predefinito: -1) specifica il numero massimo di connessioni in entrata simultanee che Edge Microgateway può ricevere. Se questo numero viene superato, viene restituito il seguente stato:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (valore predefinito: -1) il numero massimo di richieste simultanee che Edge Microgateway può ricevere prima di chiudere la connessione. Questa impostazione ha lo scopo di contrastare gli attacchi denial of service. In genere, impostalo su un numero maggiore di max_connections.
• logging:
  • level: (valore predefinito: error)
    • info: registra tutte le richieste e le risposte che passano attraverso un'istanza di Edge Microgateway.
    • warn: registra solo i messaggi di avviso.
    • error: registra solo i messaggi di errore.
  • dir: (valore predefinito: /var/tmp) la directory in cui sono archiviati i file di log.
  • stats_log_interval: (valore predefinito: 60) intervallo, in secondi, in cui il record delle statistiche viene scritto nel file di log dell'API.
  • rotate_interval: (valore predefinito: 24) intervallo, in ore, in cui i file di log vengono ruotati.

• plugins: i plug-in aggiungono funzionalità a Edge Microgateway. Per informazioni dettagliate sullo sviluppo di plug-in, consulta Sviluppa plug-in personalizzati.

• dir: un percorso relativo dalla directory ./gateway alla directory ./plugins o un percorso assoluto.
• sequence: un elenco di moduli di plug-in da aggiungere all'istanza di Edge Microgateway. I moduli verranno eseguiti nell'ordine in cui sono specificati qui.

• debug: aggiunge il debug remoto al processo Edge Microgateway.
  • port: il numero di porta su cui ascoltare. Ad esempio, imposta il debugger dell'IDE in modo che ascolti su questa porta.
  • args: argomenti per il processo di debug. Ad esempio: args --nolazy
    
• config_change_poll_interval: (valore predefinito: 600 secondi) Edge Microgateway carica periodicamente una nuova configurazione ed esegue un ricaricamento se sono state apportate modifiche. Il polling rileva eventuali modifiche apportate su Edge (modifiche ai prodotti, proxy compatibili con microgateway e così via), nonché le modifiche apportate al file di configurazione locale.
  
• disable_config_poll_interval: (valore predefinito: false) Imposta su true per disattivare il polling automatico delle modifiche.
• request_timeout: imposta un timeout per le richieste di destinazione. Il timeout è impostato in secondi. Se si verifica un timeout, Edge Microgateway risponde con un codice di stato 504. (Aggiunto v2.4.x)

attributi headers

Queste impostazioni configurano il modo in cui vengono trattate determinate intestazioni HTTP.

• x-forwarded-for: (valore predefinito: true) imposta su false per impedire il passaggio delle intestazioni x-forwarded-for alla destinazione. Tieni presente che se nella richiesta è presente un'intestazione x-forwarded-for, il suo valore verrà impostato sul valore client-ip in Edge Analytics.
• x-forwarded-host: (valore predefinito: true) imposta su false per impedire il passaggio delle intestazioni x-forwarded-host alla destinazione.
• x-request-id: (valore predefinito: true) imposta su false per impedire il passaggio delle intestazioni x-request-id alla destinazione.
• x-response-time: (valore predefinito: true) imposta su false per impedire che le intestazioni x-response-time vengano passate alla destinazione.
• via: (valore predefinito: true) imposta su false per impedire che le intestazioni via vengano passate alla destinazione.

attributi oauth

Queste impostazioni configurano il modo in cui l'autenticazione client viene applicata da Edge Microgateway.

• allowNoAuthorization: (valore predefinito: false) se impostato su true, le chiamate API possono passare attraverso Edge Microgateway senza alcuna intestazione Authorization. Imposta questo valore su false per richiedere un'intestazione Authorization (valore predefinito).
• allowInvalidAuthorization: (valore predefinito: false) se impostato su true, le chiamate API possono essere eseguite se il token passato nell'intestazione Authorization non è valido o è scaduto. Imposta questo valore su false per richiedere token validi (impostazione predefinita).
• authorization-header: (valore predefinito: Authorization: Bearer) l'intestazione utilizzata per inviare il token di accesso a Edge Microgateway. Potresti voler modificare l'impostazione predefinita nei casi in cui la destinazione deve utilizzare l'intestazione Authorization per altri scopi.
• api-key-header: (valore predefinito: x-api-key) il nome dell'intestazione o del parametro di query utilizzato per passare una chiave API a Edge Microgateway. Consulta anche Utilizzo di una chiave API.
• keep-authorization-header: (valore predefinito: false) se impostato su true, l'intestazione Authorization inviata nella richiesta viene trasmessa alla destinazione (viene conservata).
• allowOAuthOnly: se impostato su true, ogni API deve contenere un'intestazione Authorization con un token di accesso Bearer. Consente di autorizzare solo il modello di sicurezza OAuth (mantenendo la compatibilità con le versioni precedenti). (Aggiunto 2.4.x)
• allowAPIKeyOnly: se impostato su true, ogni API deve contenere un'intestazione x-api-key (o una posizione personalizzata) con una chiave API.Consente di autorizzare solo il modello di sicurezza della chiave API (mantenendo la compatibilità con le versioni precedenti). (Aggiunto 2.4.x)
• gracePeriod: questo parametro aiuta a prevenire gli errori causati da lievi discrepanze tra l'orologio di sistema e gli orari Not Before (nbf) o Issued At (iat) specificati nel token di autorizzazione JWT. Imposta questo parametro sul numero di secondi da consentire per queste discrepanze. (Aggiunto 2.5.7)

Attributi specifici del plug-in

Per informazioni dettagliate sugli attributi configurabili per ogni plug-in, consulta Utilizzo dei plug-in.

Proxy di filtro

Puoi filtrare i proxy compatibili con il microgateway che verranno elaborati da un'istanza di Edge Microgateway. All'avvio, Edge Microgateway scarica tutti i proxy compatibili con Microgateway nell'organizzazione a cui è associato. Utilizza la seguente configurazione per limitare i proxy che verranno elaborati dal microgateway. Ad esempio, questa configurazione limita a tre i proxy che il microgateway elaborerà: edgemicro_proxy-1, edgemicro_proxy-2 e edgemicro_proxy-3:

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Configurazione della frequenza di push di Analytics

Utilizza questi parametri di configurazione per controllare la frequenza con cui Edge Microgateway invia i dati di analisi ad Apigee:

• bufferSize (facoltativo): il numero massimo di record di analisi che il buffer può contenere prima di iniziare a eliminare i record meno recenti. Valore predefinito: 10000
• batchSize (facoltativo): la dimensione massima di un batch di record di analisi inviati ad Apigee. Valore predefinito: 500
• flushInterval (facoltativo): il numero di millisecondi tra ogni svuotamento di un batch di record di analisi inviati ad Apigee. Valore predefinito: 5000

Ad esempio:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Mascheramento dei dati di analisi

La seguente configurazione impedisce la visualizzazione delle informazioni sul percorso della richiesta in Edge Analytics. Aggiungi quanto segue alla configurazione del microgateway per mascherare l'URI della richiesta e/o il percorso della richiesta. Tieni presente che l'URI è costituito dalle parti del nome host e del percorso della richiesta.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Segregazione delle chiamate API in Edge Analytics

Puoi configurare il plug-in di analisi in modo da separare un percorso API specifico in modo che venga visualizzato come proxy separato nelle dashboard di Edge Analytics. Ad esempio, puoi separare un'API di controllo di integrità nella dashboard per evitare di confonderla con le chiamate proxy API effettive. Nella dashboard di Analytics, i proxy separati seguono questo pattern di denominazione:

edgemicro_proxyname-health

La seguente immagine mostra due proxy separati nella dashboard di Analytics: edgemicro_hello-health e edgemicro_mock-health:

Utilizza questi parametri per separare i percorsi relativi e assoluti nella dashboard di Analytics come proxy separati:

• relativePath (facoltativo): specifica un percorso relativo da separare nella dashboard di Analytics. Ad esempio, se specifichi /healthcheck, tutte le chiamate API che contengono il percorso /healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health. Tieni presente che questo flag ignora il percorso di base del proxy. Per separare in base a un percorso completo, incluso il percorso di base, utilizza il flag proxyPath.
• proxyPath (facoltativo): specifica un percorso proxy API completo, incluso il percorso di base del proxy, da separare nella dashboard di analisi. Ad esempio, se specifichi /mocktarget/healthcheck, dove /mocktarget è il percorso di base del proxy, tutte le chiamate API con il percorso /mocktarget/healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health.

Ad esempio, nella seguente configurazione, qualsiasi percorso API che contiene /healthcheck verrà segregato dal plug-in di analisi. Ciò significa che /foo/healthcheck e /foo/bar/healthcheck verranno separati come proxy separato denominato edgemicro_proxyname-health nella dashboard di analisi.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Nella seguente configurazione, qualsiasi API con il percorso proxy /mocktarget/healthcheck verrà separata come proxy distinto denominato edgemicro_proxyname-health nella dashboard di analisi.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Configurazione di Edge Microgateway dietro un firewall aziendale

Supportato v2.4.x

Se Edge Microgateway è installato dietro un firewall, il gateway potrebbe non essere in grado di comunicare con Apigee Edge. In questo caso, puoi prendere in considerazione due opzioni:

Opzione 1:

La prima opzione consiste nell'impostare l'opzione edgemicro: proxy_tunnel su true nel file di configurazione di Microgateway:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

Quando proxy_tunnel è true, Edge Microgateway utilizza il metodo HTTP CONNECT per eseguire il tunneling delle richieste HTTP su una singola connessione TCP. Lo stesso vale se le variabili di ambiente per la configurazione del proxy sono abilitate per TLS.

Opzione 2:

La seconda opzione consiste nello specificare un proxy e impostare proxy_tunnel su false nel file di configurazione del microgateway. Ad esempio:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

In questo caso, puoi impostare le seguenti variabili per controllare gli host per ogni proxy HTTP che vuoi utilizzare o quali host non devono gestire i proxy Edge Microgateway: HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

Puoi impostare NO_PROXY come elenco di domini delimitati da virgole a cui Edge Microgateway non deve eseguire il proxy. Ad esempio:

export NO_PROXY='localhost,localhost:8080'

Imposta HTTP_PROXY e HTTPS_PROXY sull'endpoint proxy HTTP in modo che Edge Microgateway possa inviargli messaggi. Ad esempio:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

Per saperne di più su queste variabili, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

Vedi anche

How to set up Edge Microgateway behind a company firewall nella community Apigee.

Utilizzo di caratteri jolly nei proxy compatibili con Microgateway

Puoi utilizzare uno o più caratteri jolly "*" nel percorso di base di un proxy edgemicro_* (compatibile con Microgateway). Ad esempio, un percorso di base /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza che tu debba creare nuovi proxy API per supportare nuovi team. Tieni presente che /**/ non è supportato.

Importante: Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo elemento di un percorso di base. Ad esempio, non è supportata la ricerca /*/.

Rotazione delle chiavi JWT

In un momento successivo alla generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM criptato di Edge. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione delle chiavi.

In che modo Edge Microgateway utilizza JWT

JSON Web Token (JWT) è uno standard di token descritto in RFC7519. Il JWT consente di firmare un insieme di attestazioni, che possono essere verificate in modo affidabile dal destinatario del JWT.

Edge Microgateway utilizza i JWT come token di connessione per la sicurezza OAuth. Quando generi un token OAuth per Edge Microgateway, ricevi un JWT. Puoi quindi utilizzare il JWT nell'intestazione Authorization delle chiamate API. Ad esempio:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Generazione di un nuovo JWT

Puoi generare un JWT per Edge Microgateway utilizzando il comando edgemicro token o un'API. Ad esempio:

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Questo comando chiede ad Apigee Edge di generare un JWT che può essere utilizzato per verificare le chiamate API. I parametri -i e -s sono i valori ID consumatore e secret di un'app per sviluppatori nella tua organizzazione Apigee Edge.

In alternativa, puoi generare un JWT utilizzando l'API di gestione:

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

Dove:

• org è il nome della tua organizzazione Edge (devi essere un amministratore dell'organizzazione).
• env è un ambiente della tua organizzazione (ad esempio "test" o "prod").
• client_id è l'ID consumatore nell'app per sviluppatori che hai creato in precedenza.
• client_secret è il Consumer Secret nell'app per sviluppatori che hai creato in precedenza.

Che cos'è la rotazione delle chiavi?

In un momento successivo alla generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM criptato di Edge. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione delle chiavi. Quando ruoti le chiavi, viene generata una nuova coppia di chiavi privata/pubblica, che viene archiviata nel KVM "microgateway" nell'organizzazione/ambiente Apigee Edge. Inoltre, la chiave pubblica precedente viene conservata insieme al valore dell'ID chiave originale.

Per generare un JWT, Edge utilizza le informazioni archiviate nel KVM criptato. Un KVM denominato microgateway è stato creato e compilato con le chiavi durante la configurazione iniziale di Edge Microgateway. Le chiavi nel KVM vengono utilizzate per firmare e criptare un JWT.

Le chiavi KVM includono:

• private_key: l'ultima chiave privata RSA (creata più di recente) utilizzata per firmare i JWT.

• public_key: il certificato più recente (creato più di recente) utilizzato per verificare i JWT firmati con private_key.

• private_key_kid: l'ID della chiave privata più recente (creata più di recente). Questo ID chiave è associato al valore private_key e viene utilizzato per supportare la rotazione delle chiavi.

• public_key1_kid: l'ID della chiave pubblica più recente (creata più di recente). Questa chiave è associata al valore public_key1 e viene utilizzata per supportare la rotazione delle chiavi. Questo valore è lo stesso del kid della chiave privata.

• public_key1: la chiave pubblica più recente (creata più di recente).

Quando esegui la rotazione delle chiavi, i valori delle chiavi esistenti vengono sostituiti nella mappa e vengono aggiunte nuove chiavi per conservare le chiavi pubbliche precedenti. Ad esempio:

• public_key2_kid: l'ID della chiave pubblica precedente. Questa chiave è associata al valore public_key2 e viene utilizzata per supportare la rotazione delle chiavi.

• public_key2: la chiave pubblica precedente.

I JWT presentati per la verifica verranno verificati utilizzando la nuova chiave pubblica. Se la verifica non va a buon fine, verrà utilizzata la chiave pubblica precedente fino alla scadenza (dopo 30 minuti). In questo modo, puoi "ruotare" le chiavi senza interrompere immediatamente il traffico API.

Come eseguire la rotazione delle chiavi

Questa sezione spiega come eseguire una rotazione delle chiavi.

Se hai configurato l'istanza di Edge Microgateway prima della versione 2.5.2

Se hai configurato l'istanza di Edge Microgateway prima della versione 2.5.2, devi eseguire i seguenti due comandi per eseguire l'upgrade del KVM e della policy di autenticazione:

upgradekvm -o org -e env -u username

Per ulteriori informazioni su questo comando, consulta Esegui l'upgrade del KVM.

Il comando successivo esegue l'upgrade del proxy edgemicro-oauth di cui è stato eseguito il deployment nella tua organizzazione Apigee quando hai configurato Edge Microgateway. Questo proxy fornisce i servizi necessari per generare i token.

upgradeauth -o org -e env -u username

Per ulteriori informazioni su questo comando, consulta Esegui l'upgrade del proxy edgemicro-auth.

Rotazione delle chiavi

Aggiungi la seguente riga al file ~/.edgemicro/org-env-config.yaml, dove devi specificare la stessa organizzazione e lo stesso ambiente che hai configurato per l'utilizzo del microgateway:

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

Esegui il comando di rotazione delle chiavi per ruotarle. Per ulteriori informazioni su questo comando, consulta Rotazione delle chiavi.

edgemicro rotatekey -o org -e env -u username -k kid_value

Ad esempio:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v6.9.1
current edgemicro version is 2.5.7
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

Il parametro -k specifica un ID chiave (kid). Questo ID viene utilizzato per trovare una chiave specifica. Edge Microgateway utilizza questo valore per scegliere tra un insieme di chiavi durante la rotazione delle chiavi. Per saperne di più, consulta la sezione 4.5 della specifica della chiave web JSON.

Dopo la rotazione delle chiavi, Edge restituisce più chiavi a Edge Microgateway. Tieni presente che nell'esempio seguente ogni chiave ha un valore "kid" (ID chiave) univoco. Il microgateway utilizza quindi queste chiavi per convalidare i token di autorizzazione. Se la convalida del token non riesce, il microgateway controlla se nel set di chiavi è presente una chiave precedente e la prova. Il formato delle chiavi restituite è JSON Web Key (JWK). Puoi leggere informazioni su questo formato nella RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Filtro dei proxy scaricati

Per impostazione predefinita, Edge Microgateway scarica tutti i proxy della tua organizzazione Edge che iniziano con il prefisso di denominazione "edgemicro_". Puoi modificare questa impostazione predefinita per scaricare i proxy i cui nomi corrispondono a un pattern.

1. Apri il file di configurazione di Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Aggiungi l'elemento proxyPattern in edge_config. Ad esempio, il seguente pattern scaricherà proxy come edgemicro_foo, edgemicro_fast ed edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Specifica dei prodotti senza proxy API

In Apigee Edge, puoi creare un prodotto API che non contiene proxy API. Questa configurazione del prodotto consente a una chiave API associata al prodotto di funzionare con qualsiasi proxy di cui è stato eseguito il deployment nella tua organizzazione. A partire dalla versione 2.5.4, Edge Microgateway supporta questa configurazione del prodotto.

Debug e risoluzione dei problemi

Connessione a un debugger

Puoi eseguire Edge Microgateway con un debugger, ad esempio node-inspector. Questo è utile per la risoluzione dei problemi e il debug dei plug-in personalizzati.

1. Riavvia Edge Microgateway in modalità di debug. Per farlo, aggiungi DEBUG=* all'inizio del comando start. Ad esempio:

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Avvia il debugger e impostalo in modo che ascolti sul numero di porta per il processo di debug.
3. Ora puoi esaminare il codice di Edge Microgateway, impostare punti di interruzione, espressioni di controllo e così via.

Puoi specificare i flag Node.js standard relativi alla modalità di debug. Ad esempio, --nolazy aiuta a eseguire il debug del codice asincrono.

Controllo dei file di log

Se riscontri problemi, assicurati di esaminare i file di log per i dettagli di esecuzione e le informazioni sugli errori. Per maggiori dettagli, vedi Gestione dei file di log.

Utilizzo della sicurezza delle chiavi API

Le chiavi API forniscono un meccanismo semplice per autenticare i client che effettuano richieste a Edge Microgateway. Puoi ottenere una chiave API copiando il valore della chiave utente (chiamata anche ID client) da un prodotto Apigee Edge che include il proxy di autenticazione Edge Microgateway.

Memorizzazione nella cache delle chiavi

Le chiavi API vengono scambiate con token di connessione, che vengono memorizzati nella cache. Puoi disattivare la memorizzazione nella cache impostando l'intestazione Cache-Control: no-cache sulle richieste in arrivo a Edge Microgateway.

Utilizzo di una chiave API

Puoi passare la chiave API in una richiesta API come parametro di query o in un'intestazione. Per impostazione predefinita, il nome dell'intestazione e del parametro di query è x-api-key.

Esempio di parametro di query:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Esempio di titoli:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Configurazione del nome della chiave API

Per impostazione predefinita, x-api-key è il nome utilizzato sia per l'intestazione della chiave API sia per il parametro di query. Puoi modificare questa impostazione predefinita nel file di configurazione, come spiegato in Apportare modifiche alla configurazione. Ad esempio, per modificare il nome in apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

In questo esempio, sia il parametro di query sia il nome dell'intestazione vengono modificati in apiKey. Il nome x-api-key non funzionerà più in entrambi i casi. Consulta anche Apportare modifiche alla configurazione.

Ad esempio:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Per saperne di più sull'utilizzo delle chiavi API con le richieste proxy, consulta Proteggi Edge Microgateway.

Utilizzo della sicurezza dei token OAuth2

Questa sezione spiega come ottenere i token di accesso e i token di aggiornamento OAuth2. I token di accesso vengono utilizzati per effettuare chiamate API sicure tramite il microgateway. I token di aggiornamento vengono utilizzati per ottenere nuovi token di accesso.

Come ottenere un token di accesso

Questa sezione spiega come utilizzare il proxy edgemicro-auth per ottenere un token di accesso.

Puoi anche ottenere un token di accesso utilizzando il comando CLI edgemicro token. Per maggiori dettagli sull'interfaccia a riga di comando, consulta Gestione dei token.

API 1

Sostituisci i nomi della tua organizzazione e del tuo ambiente nell'URL e sostituisci i valori ID consumatore e secret consumer ottenuti da un'app per sviluppatori su Apigee Edge con i parametri del corpo client_id e client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Esempio di output

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Come ottenere un token di aggiornamento

Per ottenere un token di aggiornamento, effettua una chiamata API all'endpoint /token del proxy edgemicro-auth. DEVI effettuare questa chiamata API con il grant type password. La procedura è descritta nei passaggi seguenti.

1. Ottieni un token di accesso e un token di aggiornamento con l'API /token. Tieni presente che il grant type è password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   L'API restituisce un token di accesso e un token di aggiornamento. La risposta è simile alla seguente:

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Ora puoi utilizzare il token di aggiornamento per ottenere un nuovo token di accesso chiamando l'endpoint /refresh della stessa API. Ad esempio:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   L'API restituisce un nuovo token di accesso. La risposta è simile alla seguente:

   {
       "token": "your-new-access-token"
       }

Monitoraggio continuo

Forever è uno strumento Node.js che riavvia automaticamente un'app Node.js nel caso in cui il processo si interrompa o si verifichi un errore. Edge Microgateway ha un file forever.json che puoi configurare per controllare quante volte e con quali intervalli Edge Microgateway deve essere riavviato. Questo file configura un servizio Forever denominato forever-monitor, che gestisce Forever in modo programmatico.

Puoi trovare il file forever.json nella directory di installazione principale di Edge Microgateway. Consulta Dove è installato Edge Microgateway. Per maggiori dettagli sulle opzioni di configurazione, consulta la documentazione di forever-monitor.

Il comando edgemicro forever include flag che consentono di specificare la posizione del file forever.json (il flag -f) e di avviare/arrestare il processo di monitoraggio Forever (il flag -a). Ad esempio:

edgemicro forever -f ~/mydir/forever.json -a start

Per saperne di più, consulta Monitoraggio continuo nel riferimento dell'interfaccia a riga di comando.

Specifica di un endpoint del file di configurazione

Se esegui più istanze di Edge Microgateway, potresti voler gestire le relative configurazioni da un'unica posizione. Per farlo, specifica un endpoint HTTP in cui Edge Micro può scaricare il proprio file di configurazione. Puoi specificare questo endpoint quando avvii Edge Micro utilizzando il flag -u.

Ad esempio:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

dove l'endpoint mgconfig restituisce i contenuti del file di configurazione. Questo è il file che, per impostazione predefinita, si trova in ~/.edgemicro e ha la convenzione di denominazione: org-env-config.yaml.

Disattivazione del buffering dei dati della connessione TCP

Puoi utilizzare l'attributo di configurazione nodelay per disattivare il buffering dei dati per le connessioni TCP utilizzate da Edge Microgateway.

Per impostazione predefinita, le connessioni TCP utilizzano l'algoritmo di Nagle per memorizzare i dati nel buffer prima di inviarli. Se imposti nodelay su true, questo comportamento viene disattivato (i dati verranno inviati immediatamente ogni volta che viene chiamato socket.write()). Per ulteriori dettagli, consulta anche la documentazione di Node.js.

Per abilitare nodelay, modifica il file di configurazione di Edge Micro come segue:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Esecuzione di Edge Microgateway in modalità autonoma

Puoi eseguire Edge Microgateway completamente disconnesso da qualsiasi dipendenza di Apigee Edge. Questo scenario, chiamato modalità autonoma, ti consente di eseguire e testare Edge Microgateway senza una connessione a internet.

In modalità autonoma, le seguenti funzionalità non funzionano, in quanto richiedono la connessione ad Apigee Edge:

• OAuth e chiave API
• Quota
• Analytics

D'altra parte, i plug-in personalizzati e l'arresto dei picchi funzionano normalmente, perché non richiedono una connessione ad Apigee Edge. Inoltre, un nuovo plug-in chiamato extauth ti consente di autorizzare le chiamate API al microgateway con un JWT in modalità autonoma.

Configurazione e avvio del gateway

Per eseguire Edge Microgateway in modalità autonoma:

1. Assicurati di aver installato Edge Microgateway versione 2.5.25 o successive. In caso contrario, devi eseguire il seguente comando per eseguire l'upgrade all'ultima versione:

   npm install -g edgemicro

   Se hai bisogno di aiuto, consulta Installazione di Edge Microgateway.

2. Crea un file di configurazione denominato come segue: $HOME/.edgemicro/org_name-env_name-config.yaml

   Ad esempio:

   vi $HOME/.edgemicro/foo-bar-config.yaml

3. Incolla il seguente codice nel file:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

4. Esporta la seguente variabile di ambiente con il valore "1":

   export EDGEMICRO_LOCAL=1

5. Esegui questo comando start, in cui fornisci i valori per creare un'istanza del proxy locale:

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Dove:

   • your_org è il nome "org" che hai utilizzato nel nome del file di configurazione.
   • your_environment è il nome "env" che hai utilizzato nel nome del file di configurazione.
   • local_proxy_name è il nome del proxy locale che verrà creato. Puoi utilizzare il nome che preferisci.
   • local_proxy_version è il numero di versione del proxy.
   • target_url è l'URL della destinazione del proxy. (La destinazione è il servizio chiamato dal proxy.)
   • base_path è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso di base principale, specifica solo una barra, ad esempio "/".

   Ad esempio:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Testa la configurazione.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Poiché il plug-in extauth si trova nel file foo-bar-config.yaml, ricevi un errore "missing_authorization". Questo plug-in convalida un JWT che deve essere presente nell'intestazione Authorization della chiamata API. Nella sezione successiva, otterrai un JWT che consentirà alle chiamate API di essere eseguite senza errori.

Esempio: ottenere un token di autorizzazione

L'esempio seguente mostra come ottenere un JWT dall'endpoint JWT di Edge Microgateway su Apigee Edge (edgemicro-auth/jwkPublicKeys). Il deployment di questo endpoint viene eseguito quando esegui una configurazione standard di Edge Microgateway. Per ottenere il JWT dall'endpoint Apigee, devi prima eseguire la configurazione standard di Edge Microgateway ed essere connesso a internet. L'endpoint Apigee viene utilizzato qui solo a scopo di esempio e non è obbligatorio. Se vuoi, puoi utilizzare un altro endpoint del token JWT. In questo caso, dovrai ottenere il JWT utilizzando l'API fornita per quell'endpoint.

I passaggi seguenti spiegano come ottenere un token utilizzando l'endpoint edgemicro-auth/jwkPublicKeys:

1. Devi eseguire una configurazione standard di Edge Microgateway per eseguire il deployment del proxy edgemicro-auth nella tua organizzazione/nel tuo ambiente su Apigee Edge. Se hai già eseguito questo passaggio, non è necessario ripeterlo.
2. Se hai eseguito il deployment di Edge Microgateway in Apigee Cloud, devi avere una connessione a internet per poter ottenere un JWT da questo endpoint.
3. Arresta Edge Microgateway:

   edgemicro stop

4. Nel file di configurazione creato in precedenza ($HOME/.edgemicro/org-env-config.yaml), indirizza l'attributo extauth:publickey_url all'endpoint edgemicro-auth/jwkPublicKeys nell'organizzazione/ambiente Apigee Edge. Ad esempio:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Riavvia Edge Microgateway come hai fatto in precedenza, utilizzando i nomi di organizzazione/ambiente che hai utilizzato nel nome del file di configurazione. Ad esempio:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Ottieni un token JWT dall'endpoint di autorizzazione. Poiché utilizzi l'endpoint edgemicro-auth/jwkPublicKeys, puoi utilizzare questo comando dell'interfaccia a riga di comando:

Puoi generare un JWT per Edge Microgateway utilizzando il comando edgemicro token o un'API. Ad esempio:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Dove:

• your_org è il nome della tua organizzazione Apigee per la quale hai configurato Edge Microgateway in precedenza.
• your_env è un ambiente nell'organizzazione.
• L'opzione i specifica la chiave utente di un'app per sviluppatori che ha un prodotto che include il proxy edgemicro-auth.
• L'opzione s specifica il client secret di un'app per sviluppatori che ha un prodotto che include il proxy edgemicro-auth.

Questo comando chiede ad Apigee Edge di generare un JWT che può essere utilizzato per verificare le chiamate API.

Testa la configurazione autonoma

Per testare la configurazione, chiama l'API con il token aggiunto nell'intestazione Authorization come segue:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Esempio:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Output di esempio:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Utilizzo della modalità proxy locale

In modalità proxy locale, Edge Microgateway non richiede il deployment di un proxy compatibile con Microgateway su Apigee Edge. Invece, configuri un "proxy locale" fornendo un nome del proxy locale, un percorso di base e un URL di destinazione quando avvii il microgateway. Le chiamate API al microgateway vengono quindi inviate all'URL di destinazione del proxy locale. In tutti gli altri aspetti, la modalità proxy locale funziona esattamente come l'esecuzione di Edge Microgateway nella modalità normale. L'autenticazione funziona allo stesso modo, così come l'arresto dei picchi e l'applicazione delle quote, i plug-in personalizzati e così via.

Caso d'uso ed esempio

La modalità proxy locale è utile quando devi associare un solo proxy a un'istanza di Edge Microgateway. Ad esempio, puoi inserire Edge Microgateway in Kubernetes come proxy sidecar, in cui un microgateway e un servizio vengono eseguiti ciascuno in un singolo pod e il microgateway gestisce il traffico da e verso il servizio associato. La figura seguente illustra questa architettura in cui Edge Microgateway funge da proxy sidecar in un cluster Kubernetes. Ogni istanza di microgateway comunica solo con un singolo endpoint sul servizio complementare:

Un vantaggio di questo stile di architettura è che Edge Microgateway fornisce la gestione delle API per i singoli servizi di cui è stato eseguito il deployment in un ambiente container, ad esempio un cluster Kubernetes.

Configurazione della modalità proxy locale

Per configurare Edge Microgateway in modo che venga eseguito in modalità proxy locale, segui questi passaggi:

1. Assicurati di aver installato Edge Microgateway versione 2.5.25 o successive. In caso contrario, devi eseguire il seguente comando per eseguire l'upgrade all'ultima versione:

   npm install -g edgemicro

   Se hai bisogno di aiuto, consulta Installazione di Edge Microgateway.

2. Esegui edgemicro init per configurare l'ambiente di configurazione locale, esattamente come faresti in una tipica configurazione di Edge Microgateway. Consulta anche Configura Edge Microgateway.
3. Esegui edgemicro configure, come faresti in una tipica procedura di configurazione di Edge Microgateway. Ad esempio:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Questo comando esegue il deployment della policy edgemicro-auth in Edge e restituisce una chiave e un secret necessari per avviare il microgateway. Se hai bisogno di aiuto, consulta Configura Edge Microgateway.

4. In Apigee Edge, crea un prodotto API con i seguenti requisiti di configurazione obbligatori (puoi gestire tutte le altre configurazioni come preferisci):
   • Devi aggiungere il proxy edgemicro-auth al prodotto. Il deployment di questo proxy è stato eseguito automaticamente quando hai eseguito edgemicro configure.
   • Devi fornire un percorso della risorsa. Apigee consiglia di aggiungere questo percorso al prodotto: /**. Per saperne di più, consulta Configurazione del comportamento del percorso della risorsa. Consulta anche Crea prodotti API nella documentazione di Edge.

5. In Apigee Edge, crea uno sviluppatore o, se preferisci, utilizzane uno esistente. Per assistenza, consulta Aggiunta di sviluppatori utilizzando la UI di gestione di Edge.

6. In Apigee Edge, crea un'app per sviluppatori. Devi aggiungere all'app il prodotto API che hai appena creato. Per assistenza, consulta Registrazione di un'app nella UI di gestione di Edge.
7. Sulla macchina in cui è installato Edge Microgateway, esporta la seguente variabile di ambiente con il valore "1".

   export EDGEMICRO_LOCAL_PROXY=1

8. Esegui questo comando start:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Dove:

   • your_org è la tua organizzazione Apigee.
   • your_environment è un ambiente della tua organizzazione.
   • your_key è la chiave restituita quando hai eseguito edgemicro configure.
   • your_secret è il secret restituito quando hai eseguito edgemicro configure.
   • local_proxy_name è il nome del proxy locale che verrà creato.
   • local_proxy_version è il numero di versione del proxy.
   • target_url è l'URL della destinazione del proxy (il servizio che verrà chiamato dal proxy).
   • base_path è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso di base principale, specifica solo una barra, ad esempio "/".

   Ad esempio:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Test della configurazione

Puoi testare la configurazione del proxy locale chiamando l'endpoint del proxy. Ad esempio, se hai specificato un percorso di base /echo, puoi chiamare il proxy come segue:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Questa chiamata API iniziale ha generato un errore perché non hai fornito una chiave API valida. Puoi trovare la chiave nell'app per sviluppatori che hai creato in precedenza. Apri l'app nell'interfaccia utente di Edge, copia la chiave utente e utilizzala come segue:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Ad esempio:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Output di esempio:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}