Riferimento per le operazioni e la configurazione di Edge Microgateway

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Microgateway Edge v. 2.4.x

Panoramica

Questo argomento illustra come gestire e configurare Edge Microgateway, inclusi monitoraggio, logging e debug.

Apportare modifiche alla configurazione

I file di configurazione che devi conoscere includono:

• File di configurazione di sistema predefinita
• File di configurazione predefinito per un'istanza Edge Microgateway appena inizializzata
• File di configurazione dinamica per l'esecuzione delle istanze

Questa sezione illustra questi file e cosa devi sapere per modificarli. Per maggiori dettagli sulle impostazioni del file di configurazione, consulta il riferimento per la configurazione di Edge Microgateway.

File di configurazione di sistema predefinita

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. Vedi Dove è installato Edge Microgateway.

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

1. Chiama edgemicro init
2. Chiama edgemicro configure [params]
3. Chiama edgemicro start [params]

File di configurazione predefinito per le istanze Edge Microgateway appena inizializzate

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

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

1. edgemicro stop
2. edgemicro configure [params]
3. edgemicro start [params]

File di configurazione dinamica per l'esecuzione delle istanze

Quando esegui edgemicro configure [params], viene creato un file di configurazione dinamica in ~/.edgemicro. Il file è denominato in base a 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, quindi ricaricarle senza tempo di inattività. Ad esempio, se aggiungi e configuri un plug-in, puoi ricaricare la configurazione senza causare tempi di inattività, come spiegato di seguito.

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

1. Ricarica la configurazione del Microgateway Edge:

   edgemicro reload -o [org] -e [env] -k [key] -s [secret]
   

   Dove:

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

   Esempio

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d000723 -s 05c14356e42ed136b8dd35cf8a18531ff52d7299134677e30ef4e34ab0cc824
   

Se Edge Microgateway è arrestato:

1. Riavvia Edge Microgateway:

   edgemicro start -o [org] -e [env] -k [key] -s [secret]
   

   Dove:

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

   Esempio

   edgemicro start -o docs -e test -k 701e70ee718ce6dc188016b3c39177d64a88754d615c74e1f78b6181d000723 -s 05c14356e42ed136b8dd35cf8a18531ff52d7299134677e30ef4e34ab0cc824
   

Ecco un file di configurazione di esempio. Per maggiori dettagli sulle impostazioni del file di configurazione, consulta il riferimento per la 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 l'avvio di 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 specificarne i 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, se è configurato SSL, puoi chiamare le API tramite Edge Microgateway con il protocollo "https", in questo modo:

https://localhost:8000/myapi

Per configurare SSL sul server Microgateway, procedi nel seguente modo:

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 del Microgateway Edge. Per un elenco completo delle opzioni, consulta la tabella seguente. Per maggiori dettagli sulla modifica della configurazione di Edge Microgateway, vedi Apportare modifiche alla configurazione. 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 modificato: il file predefinito o il file di configurazione del runtime.

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

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 di server supportate:

Utilizzo delle opzioni SSL/TLS del client

Puoi configurare Edge Microgateway come client TLS o SSL durante la connessione agli endpoint di destinazione. Nel file di configurazione del microgateway, utilizza l'elemento target per impostare le opzioni SSL/TLS.

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

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:

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:

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

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

Personalizzazione del proxy di autenticazione perimetrale

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 è stato eseguito quando esegui la prima volta edgemicro configure. Puoi modificare la configurazione predefinita di questo proxy per aggiungere il supporto per le attestazioni personalizzate a un token JWT (JSON Web Token), configurare la scadenza dei token e generare token di aggiornamento. Per maggiori dettagli, consulta la pagina edgemicro-auth in 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 è stato eseguito quando esegui la prima volta edgemicro configure. 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 un 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 relative a 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 sono archiviati in /var/tmp.

Come modificare la directory predefinita del file di log

La directory in cui sono archiviati i file di log è specificata nel file di configurazione Edge Microgateway. Per maggiori dettagli su come apportare modifiche alla configurazione, vedi 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 del file di log diversa.

Invia i log alla console

Puoi configurare il logging in modo che le informazioni di log vengano inviate a un 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 all'esterno standard. Al momento, non puoi inviare log sia a stdout sia a un file di log.

Come impostare il livello di logging

Puoi impostare i seguenti livelli di log: informazioni, avviso ed errore. Il livello di informazione è consigliato. Registra tutte le richieste e le risposte API ed è l'impostazione predefinita.

Come modificare gli intervalli dei log

Puoi configurare questi intervalli nel file di configurazione di Edge Microgateway. Per maggiori dettagli su come apportare modifiche alla configurazione, consulta 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, durante la rotazione dei file di log. 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

Nota : i file di log archiviati non vengono compressi. All'inizio dell'intervallo, viene creato un nuovo file di log con un nuovo timestamp.

Buone prassi di 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 molto grandi, assicurati che la directory del file di log disponga di spazio sufficiente. Consulta le seguenti sezioni 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 il criterio prevede l'eliminazione dei log, puoi utilizzare il comando dell'interfaccia a riga di comando edgemicro log -c per rimuovere (ripulire) i log meno recenti.

Convenzione di denominazione dei file di log

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

• api: registra tutte le richieste e risposte che passano attraverso Edge Microgateway. In questo file vengono registrati anche gli errori e i contatori (statistiche) 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

Aggiunto in: v2.3.3

Per impostazione predefinita, il servizio di logging omette il JSON dei proxy scaricati, dei prodotti e del token JWT (JSON Web Token). Se vuoi generare questi oggetti nei file di log, imposta DEBUG=* all'avvio di Edge Microgateway. Ad esempio:

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

Nota: su Windows, utilizza SET DEBUG=*

Contenuti del file di log "api"

Il file di log "api" contiene informazioni dettagliate sul flusso di richieste e risposte attraverso Edge Microgateway. I file di log "api" hanno il seguente nome:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

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

• Richiesta in arrivo dal client
• Richiesta in uscita effettuata alla destinazione
• Risposta in arrivo dal target
• Risposta in uscita per il client

Ognuna di queste voci separate è rappresentata in una notazione abbreviata per aiutare a rendere i file di log più compatti. Ecco quattro voci di esempio che rappresentano ciascuno dei quattro eventi. Nel file di log, avranno il seguente aspetto (i numeri di riga sono solo come riferimento nel documento, non compaiono 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

Vediamole una per una:

1. Esempio di richiesta in entrata dal client:

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

• 1436403888651 - Indicatore data Unix
• informazioni: dipendono dal contesto. Può trattarsi di informazioni, avvisi o errori, a seconda del livello di log. Può trattarsi di statistiche per un record di statistiche, avvisi per avvisi o errori per errori.
• req: identifica l'evento. In questo caso, richiedi una richiesta del client.
• m: il verbo HTTP utilizzato nella richiesta.
• u: la parte dell'URL che segue il percorso base.
• h: l'host e il numero di porta su cui Edge Microgateway è in ascolto.
• r: l'host remoto e la porta da cui ha avuto origine la richiesta del client.
• i: l'ID della richiesta. Le quattro voci dell'evento condivideranno questo ID. A ogni richiesta viene assegnato un ID richiesta univoco. La correlazione dei record di log per ID richiesta può fornire insight preziosi sulla latenza della destinazione.
• d: la durata in millisecondi da quando la richiesta è stata ricevuta da Edge Microgateway. Nell'esempio precedente, la risposta del target 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 delle richieste è stata di 11 millisecondi, di cui 7 millisecondi sono stati ricavati dal target e 4 millisecondi dallo stesso Edge Microgateway.

2. Esempio di richiesta in uscita inviata alla destinazione:

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

• 1436403888651 - Indicatore data Unix
• informazioni: dipendono dal contesto. Può trattarsi di informazioni, avvisi o errori, a seconda del livello di log. Può trattarsi di statistiche per un record di statistiche, avvisi per avvisi o errori per errori.
• treq: identifica l'evento. In questo caso, target request.
• m: il verbo HTTP utilizzato nella richiesta di destinazione.
• u: la parte dell'URL che segue il percorso base.
• h: l'host e il numero di porta della destinazione del backend.
• i: l'ID della voce di log. Le quattro voci evento condivideranno questo ID.

3. Esempio di risposta in arrivo dal target

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

1436403888651 - Indicatore data Unix

• informazioni: dipendono dal contesto. Può trattarsi di informazioni, avvisi o errori, a seconda del livello di log. Può trattarsi di statistiche per un record di statistiche, avvisi per avvisi o errori per errori.
• tres: identifica l'evento. In questo caso, risposta target.
• s: lo stato della risposta HTTP.
• d - La durata in millisecondi. Il tempo impiegato dal target per la chiamata API.
• i: l'ID della voce di log. Le quattro voci evento condivideranno questo ID.

4. Esempio di risposta in uscita al client

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

1436403888651 - Indicatore data Unix

• informazioni: dipendono dal contesto. Può trattarsi di informazioni, avvisi o errori, a seconda del livello di log. Può trattarsi di statistiche per un record di statistiche, avvisi per avvisi o errori per errori.
• res: identifica l'evento. In questo caso, la risposta al client.
• s: lo stato della risposta HTTP.
• d - La durata in millisecondi. Questo è il tempo totale impiegato dalla chiamata API, che include il tempo impiegato dall'API target e quello impiegato da Edge Microgateway stesso.
• i: l'ID della voce di log. Le quattro voci evento condivideranno questo ID.

Pianificazione del 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. Vedi anche Buone prassi di manutenzione dei file di log.

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

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

edge_config:

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

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

export NO_PROXY='localhost,localhost:8080'

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

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

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