Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Microgateway Edge v. 2.5.x
Questo argomento illustra come gestire e configurare Edge Microgateway.
Upgrade di Edge Microgateway se hai una connessione a internet
- 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 la versione più recente. Ad esempio, per eseguire l'upgrade alla versione 2.5.26, utilizza il comando seguente:
npm upgrade edgemicro@2.5.26 -g
- Controlla il numero della 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
- Infine, esegui l'upgrade alla versione più recente 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 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.
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
. Se non riesci a trovare questa directory, vedi
Dove è installato Edge Microgateway.
Se modifichi il file di configurazione di sistema, devi reinizializzare, riconfigurare e riavviare Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
File di configurazione predefinito per le istanze Edge Microgateway appena inizializzate
Quando esegui edgemicro init
, il file di configurazione del 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 stopedgemicro configure [params]
edgemicro start [params]
File di configurazione dinamica per l'esecuzione delle istanze
Quando esegui edgemicro configure [params]
, in ~/.edgemicro
viene creato un
file di configurazione dinamica. 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à):
- Ricarica la configurazione del Microgateway Edge:
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 è arrestato:
- 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 maggiori dettagli sulle impostazioni del file di configurazione, vedi 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:
- Genera o ottieni un certificato e una chiave SSL utilizzando l'utilità openssl o il metodo che preferisci.
- Aggiungi l'attributo
edgemicro:ssl
al file di configurazione 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
- 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, in cui è configurato il protocollo 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:
Opzione | Descrizione |
---|---|
key |
Percorso di un file ca.key (in formato PEM). |
cert |
Percorso di un file ca.cert (in formato PEM). |
pfx |
Percorso di un file pfx contenente la chiave privata, il certificato e i certificati CA del client in formato PFX. |
passphrase |
Una stringa contenente la passphrase per la chiave privata o PFX. |
ca |
Percorso di un file contenente un elenco di certificati attendibili in formato PEM. |
ciphers |
Una stringa che descrive le crittografie da utilizzare separate da ":". |
rejectUnauthorized |
Se il valore è true, il certificato del server viene verificato in base all'elenco di CA fornite. Se la verifica non va a buon fine, viene restituito un errore. |
secureProtocol |
Il metodo SSL da utilizzare. Ad esempio, SSLv3_method per forzare SSL alla versione 3. |
servername |
Il nome del server per l'estensione TLS SNI (Server Name Indication). |
requestCert |
true per SSL a due vie; false per SSL unidirezionale |
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:
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
Di seguito è riportato un elenco di tutte le opzioni client supportate:
Opzione | Descrizione |
---|---|
pfx |
Percorso di un file pfx contenente la chiave privata, il certificato e i certificati CA del client in formato PFX. |
key |
Percorso di un file ca.key (in formato PEM). |
passphrase |
Una stringa contenente la passphrase per la chiave privata o PFX. |
cert |
Percorso di un file ca.cert (in formato PEM). |
ca |
Percorso di un file contenente un elenco di certificati attendibili in formato PEM. |
ciphers |
Una stringa che descrive le crittografie da utilizzare separate da ":". |
rejectUnauthorized |
Se il valore è true, il certificato del server viene verificato in base all'elenco di CA fornite. Se la verifica non va a buon fine, viene restituito un errore. |
secureProtocol |
Il metodo SSL da utilizzare. Ad esempio, SSLv3_method per forzare SSL alla versione 3. |
servername |
Il nome del server per l'estensione TLS SNI (Server Name Indication). |
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. Vedi 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 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. Vedi 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, 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
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 (pulire) 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
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.
Messaggi di errore
Alcune voci di log conterranno messaggi di errore. Per identificare dove e perché si verificano gli errori, consulta la documentazione di riferimento sugli errori Microgateway Edge.
Riferimento per la configurazione di Edge Microgateway
Percorso del file di configurazione
Gli attributi di configurazione descritti in questa sezione si trovano nel file di configurazione di Edge Microgateway. Vedi anche Apportare modifiche alla configurazione.
Attributi edge_config
Queste impostazioni vengono utilizzate per configurare l'interazione tra l'istanza Edge Microgateway e Apigee Edge.
- bootstrap: (predefinito: nessuno) un URL che rimanda a un servizio specifico del Microgateway Edge 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 e configurazione di Edge Microgateway. - jwt_public_key: (predefinito: nessuno) un URL che rimanda 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 eseguire il deployment del proxy: edgemicro configure. Per maggiori dettagli, consulta Configurazione e configurazione di Edge Microgateway.
Attributi edgemicro
Queste impostazioni configurano il processo Edge Microgateway.
- port: (predefinito: 8000) il numero di porta su cui il processo Edge Microgateway è 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: (predefinito: -1) il numero massimo di richieste simultanee che Edge Microgateway può ricevere prima di arrestare la connessione. Questa impostazione ha lo scopo di impedire gli attacchi denial of service. In genere, impostalo su un numero maggiore di max_connections.
-
:
-
level: (predefinito: errore)
- informazioni: registra tutte le richieste e le risposte che passano attraverso un'istanza Edge Microgateway.
- warn: registra solo i messaggi di avviso.
- error: registra solo i messaggi di errore.
- dir: (impostazione predefinita: /var/tmp) la directory in cui vengono archiviati i file di log.
- stats_log_interval: (valore predefinito: 60): intervallo, in secondi, durante il quale 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.
-
level: (predefinito: errore)
- plug-in: i plug-in aggiungono funzionalità a Edge Microgateway. Per maggiori dettagli sullo sviluppo di plug-in, consulta l'articolo Sviluppare plug-in personalizzati.
- dir: un percorso relativo dalla directory ./gateway alla directory ./plugins o un percorso assoluto.
- Sequenza: un elenco di moduli plug-in da aggiungere all'istanza Edge Microgateway. I moduli verranno eseguiti nell'ordine specificato qui.
-
debug: aggiunge il debug remoto al processo Edge Microgateway.
- porta: il numero di porta su cui rimanere in ascolto. Ad esempio, imposta il debugger IDE per l'ascolto su questa porta.
- args: argomenti del 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 in caso di modifiche. Il polling rileva tutte le modifiche apportate su Edge (modifiche ai prodotti, ai proxy sensibili al microgateway e così via) e alle modifiche apportate al file di configurazione locale.
- disable_config_poll_interval: (impostazione predefinita: 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. (Aggiunta v2.4.x)
attributi header
Queste impostazioni configurano il modo in cui vengono trattate determinate intestazioni HTTP.
- x-forwarded-for: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-forwarded-for alla destinazione. Tieni presente che, se la richiesta contiene un'intestazione x-forwarded-for, il relativo valore verrà impostato sul valore client-ip in Edge Analytics.
- x-forwarded-host: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-forwarded-host alla destinazione.
- x-request-id: (valore predefinito: true) impostalo su false per impedire il trasferimento delle intestazioni x-request-id alla destinazione.
- x-response-time: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-response-time al target.
- via: (predefinito: true) viene impostato su false per impedire il trasferimento tramite intestazioni alla destinazione.
Attributi OAuth
Queste impostazioni configurano il modo in cui l'autenticazione client viene applicata da Edge Microgateway.
- allowNoAuthorization: (predefinito: false) se viene impostato su true, le chiamate API possono passare attraverso Edge Microgateway senza alcuna intestazione Authorization. Impostalo su false per richiedere un'intestazione di autorizzazione (impostazione predefinita).
- allowInvalidAuthorization: (valore predefinito: false) se impostato su true, le chiamate API possono essere trasmesse se il token trasmesso nell'intestazione Authorization non è valido o è scaduto. Impostalo su false per richiedere token validi (impostazione predefinita).
- permission-header: (predefinito: Authorization: Bearer) l'intestazione utilizzata per inviare il token di accesso a Edge Microgateway. Puoi modificare l'impostazione predefinita nei casi in cui la destinazione debba utilizzare l'intestazione Authorization per altri scopi.
- api-key-header: (predefinito: x-api-key) il nome dell'intestazione o del parametro di query utilizzato per passare una chiave API a Edge Microgateway. Vedi anche Utilizzo di una chiave API.
- keep-permissions-header: (impostazione predefinita: false) se è impostata su true, l'intestazione Authorization inviata nella richiesta viene trasmessa alla destinazione (viene conservata).
- allowOAuthOnly: se è impostato su true, ogni API deve includere un'intestazione Authorization con un token di accesso di connessione. Consente di consentire solo il modello di sicurezza OAuth (mantenendo la compatibilità con le versioni precedenti). (2.4.x aggiunta)
- allowAPIKeyOnly: se è impostata su true, ogni API deve avere 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. (Aggiunta 2.4.x)
- gracePeriod: questo parametro consente di evitare errori causati da lievi discrepanze tra l'orologio di sistema e gli orari Non prima (nbf) o Emesso alle (iat) specificati nel token di autorizzazione JWT. Imposta questo parametro sul numero di secondi per consentire queste discrepanze. (Aggiunta 2.5.7)
Attributi specifici dei plug-in
Per informazioni dettagliate sugli attributi configurabili per ciascun plug-in, consulta la sezione Utilizzo dei plug-in.
Filtro proxy
Puoi filtrare i proxy con rilevamento del microgateway che verranno elaborati da un'istanza Edge Microgateway.
All'avvio, Edge Microgateway scarica tutti i proxy con accesso sensibile al gateway nell'organizzazione a cui è associato. Utilizza la configurazione seguente per limitare i proxy che verranno elaborati dal microgateway. Ad esempio, questa configurazione limita a tre i proxy che verranno elaborati dal microgateway: edgemicro_proxy-1
, edgemicro_proxy-2
e edgemicro_proxy-3
:
proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
Configurazione della frequenza 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: 10.000
- batchSize (facoltativo): la dimensione massima di un batch di record di analisi inviato ad Apigee. Valore predefinito: 500
- flushInterval (facoltativo): il numero di millisecondi tra ogni svuotamento di un batch di record di analisi inviato ad Apigee. Valore predefinito: 5000
Ad esempio:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
Mascheramento dei dati di analisi
La configurazione seguente impedisce la visualizzazione delle informazioni sul percorso della richiesta nell'analisi Edge. 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'
Separazione delle chiamate API in Edge Analytics
Puoi configurare il plug-in di analisi in modo da separare un percorso dell'API specifico in modo che venga visualizzato come proxy separato nelle dashboard di Edge Analytics. Ad esempio, puoi isolare un'API per il controllo di integrità nella dashboard per evitare di confonderla con le chiamate proxy API effettive. Nella dashboard di Analytics, i proxy separati seguono questo modello di denominazione:
edgemicro_proxyname-health
L'immagine seguente 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 contenenti il percorso/healthcheck
verranno visualizzate nella dashboard comeedgemicro_proxyname-health
. Tieni presente che questo flag ignora il percorso base del proxy. Per isolare in base a un percorso completo, incluso il percorso base, utilizza il flagproxyPath
. - proxyPath (facoltativo): specifica un percorso proxy API completo, incluso il percorso base del proxy, da separare nella dashboard di analisi. Ad esempio, se specifichi
/mocktarget/healthcheck
, dove/mocktarget
è il percorso base del proxy, tutte le chiamate API con il percorso/mocktarget/healthcheck
verranno visualizzate nella dashboard comeedgemicro_proxyname-health
.
Ad esempio, nella seguente configurazione, qualsiasi percorso API contenente /healthcheck
verrà separato 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 configurazione seguente, tutte le API con il percorso proxy /mocktarget/healthcheck
verranno separate 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 proxyPath: /mocktarget/healthcheck
Configurazione di Edge Microgateway protetto da un firewall aziendale
Versione 2.4.x supportata
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 è impostare l'opzione edgemicro: proxy_tunnel su true nel file di configurazione del 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 variabili seguenti 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 delimitato da virgole di domini a cui Edge Microgateway non deve effettuare il proxy. Ad esempio:
export NO_PROXY='localhost,localhost:8080'
Imposta HTTP_PROXY e HTTPS_PROXY sull'endpoint del proxy HTTP che Edge Microgateway può inviare messaggi. Ad esempio:
export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786'
Per ulteriori informazioni su queste variabili, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
Vedi anche
Come configurare Edge Microgateway dietro un firewall aziendale nella community Apigee.
Utilizzo di caratteri jolly nei proxy sensibili al Microgateway
Puoi utilizzare uno o più caratteri jolly "*" nel percorso di base di un proxy edgemicro_* (microgateway-aware). Ad esempio, un percorso di base di /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza dover creare nuovi proxy API per supportare i 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 di /*/
.
Rotazione delle chiavi JWT
Poco tempo dopo la generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM con crittografia perimetrale. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione della chiave.
In che modo Edge Microgateway utilizza JWT
JSON Web Token (JWT) è uno standard di token descritto in RFC7519. JWT fornisce un modo per firmare un insieme di attestazioni, che possono essere verificate in modo affidabile dal destinatario del JWT.
Edge Microgateway utilizza JWT come token di connessione per la sicurezza OAuth. Quando generi un token OAuth per Edge Microgateway, ricevi un JWT. Puoi quindi utilizzare 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 dell'ID consumer e del secret di un'app sviluppatore nella tua organizzazione Apigee Edge.
In alternativa, puoi anche 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 sviluppatore che hai creato in precedenza.
- client_secret è il secret del consumatore nell'app per sviluppatori che hai creato in precedenza.
Che cos'è la rotazione della chiave?
Poco tempo dopo la generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM con crittografia perimetrale. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione della chiave. Quando ruoti le chiavi, viene generata e archiviata una nuova coppia di chiavi privata/pubblica nel KVM "microgateway" dell'organizzazione/dell'ambiente Apigee Edge. Inoltre, la vecchia chiave pubblica viene mantenuta insieme al valore ID chiave originale.
Per generare un JWT, Edge utilizza le informazioni archiviate nel KVM criptato. Un
KVM chiamato microgateway
è stato creato e completato con le chiavi quando hai inizialmente configurato (configurato)
Edge Microgateway. Le chiavi nel KVM vengono utilizzate per firmare e criptare un JWT.
Le chiavi KVM includono:
-
private_key: la 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 la 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 della chiave.
-
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 corrisponde a quello del bambino 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 della chiave.
-
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 della chiave
Questa sezione spiega come eseguire una rotazione della chiave.
Se hai configurato l'istanza Edge Microgateway prima della versione 2.5.2
Se hai configurato l'istanza Edge Microgateway prima della versione 2.5.2, devi eseguire i due comandi seguenti per eseguire l'upgrade del KVM e del criterio di autenticazione:
upgradekvm -o org -e env -u username
Per ulteriori informazioni su questo comando, consulta la sezione 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 token.
upgradeauth -o org -e env -u username
Per ulteriori informazioni su questo comando, consulta Upgrade del proxy di autenticazione 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 per cui hai configurato il microgateway:
jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'
Esegui il comando di rotazione delle chiavi per ruotare le chiavi. Per maggiori informazioni su questo comando, consulta la sezione 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 (bambino). Questo ID viene utilizzato per associare una chiave specifica.
Edge Microgateway utilizza questo valore per scegliere tra un set di chiavi durante la rotazione della chiave. Per maggiori
informazioni, consulta la Sezione 4.5 della
specifica JSON Web Key.
Dopo la rotazione della chiave, Edge restituisce più chiavi a Edge Microgateway. 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 va a buon fine, il microgateway controlla se nel set di chiavi è presente una chiave precedente e prova a trovarla. Il formato delle chiavi restituite è JSON Web Key (JWK). Puoi trovare informazioni su questo formato in 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 nella 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.
- Apri il file di configurazione Edge Micro:
~/.edgemicro/org-env-config.yaml
- 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 di utilizzare una chiave API associata al prodotto con qualsiasi proxy implementato 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, come node-inspector. Ciò è utile per la risoluzione dei problemi e il debug dei plug-in personalizzati.
- Riavvia Edge Microgateway in modalità di debug. Per farlo, aggiungi
DEBUG=*
all'inizio del comandostart
. Ad esempio:DEBUG=* edgemicro start -o myorg -e test -k db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s 6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed
- Avvia il debugger e impostalo per l'ascolto sul numero di porta per il processo di debug.
- Ora puoi esaminare il codice 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
In caso di problemi, assicurati di esaminare i file di log per trovare dettagli sull'esecuzione e informazioni sugli errori. Per maggiori dettagli, vedi Gestione dei file di log.
Utilizzo della sicurezza delle chiavi API
Le chiavi API offrono un meccanismo semplice per autenticare i client che effettuano richieste a Edge Microgateway. Puoi ottenere una chiave API copiando il valore della chiave utente (detto anche ID client) da un prodotto Apigee Edge che include il proxy di autenticazione Edge Microgateway.
Memorizzazione nella cache dei tasti
Le chiavi API vengono scambiate con i token di connessione, che vengono memorizzati nella cache. Puoi disabilitare la memorizzazione nella cache impostando l'intestazione Cache-Control: no-cache
sulle richieste in entrata a Edge Microgateway.
Utilizzo di una chiave API
Puoi passare la chiave API in una richiesta API come parametro di ricerca o in un'intestazione. Per impostazione predefinita,
il nome del parametro di intestazione e della query sono entrambi x-api-key
.
Esempio di parametro di ricerca:
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 ricerca.
Puoi modificare questa impostazione predefinita nel file di configurazione, come spiegato nella sezione Apportare modifiche alla configurazione. Ad esempio, per modificare il nome in apiKey:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
In questo esempio, il parametro di ricerca e il nome dell'intestazione sono stati modificati in apiKey
. Il
nome x-api-key
non funzionerà più in nessuno dei due casi. Vedi anche
Apportare modifiche alla configurazione.
Ad esempio:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Per maggiori informazioni sull'utilizzo delle chiavi API con le richieste proxy, consulta Secure Edge Microgateway.
Utilizzo della sicurezza del 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 attraverso 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 dell'interfaccia a riga di comando edgemicro token
.
Per maggiori dettagli sull'interfaccia a riga di comando, vedi Gestire i token.
API 1
Sostituisci i nomi dell'organizzazione e dell'ambiente nell'URL e sostituisci i valori dell'ID e del secret del consumatore ottenuti da un'app per sviluppatori su Apigee Edge con i parametri 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
(Aggiunta nella v2.5.31) Invia le credenziali client come intestazione dell'autenticazione di base egrant_type
come parametro del modulo. Questo modulo di comando è discusso anche in RFC 6749: il framework di autorizzazione OAuth 2.0.
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
L'API restituisce una risposta JSON. Tieni presente che non esiste alcuna differenza tra le proprietàtoken
e access_token
. Puoi utilizzare uno dei due metodi.
{ "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 tipo di autorizzazione password
. La procedura viene descritta di seguito.
- Ottieni un token di accesso e aggiornamento con l'API
/token
. Tieni presente che il tipo di autorizzazione è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 a questa:
{ "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" }
- 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 costante
Forever è uno strumento Node.js che riavvia automaticamente un'app Node.js nel caso in cui il processo non vada a buon fine 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 root di Edge Microgateway. Vedi 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/interrompere il processo di monitoraggio continuo (il flag -a
). Ad esempio:
edgemicro forever -f ~/mydir/forever.json -a start
Per ulteriori informazioni, consulta la sezione Monitoraggio permanente nel riferimento dell'interfaccia a riga di comando.
Specifica di un endpoint del file di configurazione
Se esegui più istanze Edge Microgateway, potresti voler gestire le relative configurazioni da un'unica località. Puoi farlo specificando 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
.
Disabilitazione del buffering dei dati della connessione TCP
Puoi utilizzare l'attributo di configurazione nodelay
per disabilitare il buffering dei dati per le connessioni TCP utilizzate da Edge Microgateway.
Per impostazione predefinita, le connessioni TCP utilizzano l'algoritmo Nagle per eseguire il buffering dei dati prima di inviarli. L'impostazione di nodelay
su true
disattiva questo comportamento (i dati verranno attivati immediatamente dopo ogni chiamata a socket.write()
). Per ulteriori dettagli, consulta anche la documentazione relativa a Node.js.
Per attivare nodelay
, modifica il file di configurazione della micro configurazione Edge 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 Apigee Edge. Questo scenario, chiamato modalità autonoma, consente di eseguire e testare Edge Microgateway senza una connessione a internet.
In modalità autonoma, le seguenti funzionalità non funzionano, poiché 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 extauth
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:
- Assicurati di avere installato Edge Microgateway versione 2.5.25 o successiva. In caso contrario, devi eseguire questo comando per eseguire l'upgrade alla versione più recente:
npm install -g edgemicro
Se hai bisogno di aiuto, vedi Installazione di Edge Microgateway.
- 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
- Incolla il codice seguente 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
- Esporta la seguente variabile di ambiente con il valore "1":
export EDGEMICRO_LOCAL=1
- Esegui questo comando
start
, in cui devi fornire 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 "organizzazione" che hai utilizzato nel nome del file di configurazione.
- your_environment è il nome "env" 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 del target del proxy. Il target è 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 /
- Testa la configurazione.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
Poiché il plug-in
extauth
si trova nel filefoo-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à l'esecuzione delle chiamate API senza l'errore.
Esempio: ottenere un token di autorizzazione
L'esempio seguente mostra come ottenere un JWT dall'endpoint JWT Edge Microgateway su Apigee Edge (edgemicro-auth/jwkPublicKeys
).
Il deployment di questo endpoint viene eseguito quando esegui una configurazione e 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
:
- Devi eseguire una configurazione standard di Edge Microgateway per eseguire il deployment del proxy
edgemicro-auth
nel tuo ambiente o nella tua organizzazione su Apigee Edge. Se hai già eseguito questo passaggio, non è necessario ripeterlo. - Se hai eseguito il deployment di Edge Microgateway in Apigee Cloud, devi disporre di una connessione a internet per poter ottenere un JWT da questo endpoint.
-
Interrompi il microgateway Edge:
edgemicro stop
- Nel file di configurazione creato in precedenza (
$HOME/.edgemicro
/org-env-config.yaml
), punta l'attributoextauth:publickey_url
all'endpointedgemicro-auth/jwkPublicKeys
nel tuo ambiente/organizzazione Apigee Edge. Ad esempio:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
Riavvia Edge Microgateway come hai fatto in precedenza, utilizzando i nomi organizzazione/ambiente utilizzati nel nome del file di configurazione. Ad esempio:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
Recupera un token JWT dall'endpoint di autorizzazione. Poiché stai utilizzando 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 cui hai precedentemente configurato Edge Microgateway.
- your_env è un ambiente dell'organizzazione.
- L'opzione
i
specifica la chiave utente di un'app per sviluppatori che ha un prodotto che include il proxyedgemicro-auth
. - L'opzione
s
specifica il consumer secret di un'app per sviluppatori che dispone di un prodotto che include il proxyedgemicro-auth
.
Questo comando chiede ad Apigee Edge di generare un JWT che può essere utilizzato per verificare le chiamate API.
Vedi anche Generare un token.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 microgateway-aware su Apigee Edge. Devi invece configurare un "proxy locale" fornendo il nome del proxy locale, il percorso base e l'URL di destinazione all'avvio del microgateway. Le chiamate API al microgateway vengono quindi inviate all'URL di destinazione del proxy locale. Sotto 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 Edge Microgateway. Ad esempio, puoi inserire Edge Microgateway in Kubernetes come proxy sidecar, dove un microgateway e un servizio vengono eseguiti ognuno in un unico pod e dove il microgateway gestisce il traffico da e verso il suo servizio companion. La figura seguente illustra questa architettura in cui Edge Microgateway funziona come proxy sidecar in un cluster Kubernetes. Ogni istanza di microgateway comunica solo con un singolo endpoint nel proprio servizio companion:
Uno dei vantaggi di questo stile di architettura è che Edge Microgateway fornisce la gestione delle API per 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:
- Assicurati di avere installato Edge Microgateway versione 2.5.25 o successiva. In caso contrario, devi eseguire questo comando per eseguire l'upgrade alla versione più recente:
npm install -g edgemicro
Se hai bisogno di aiuto, vedi Installazione di Edge Microgateway.
- Esegui
edgemicro init
per configurare il tuo ambiente di configurazione locale, esattamente come faresti in una tipica configurazione di Edge Microgateway. Vedi anche Configurare Edge Microgateway. - 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 del criterio edgemicro-auth su Edge e restituisce una chiave e un secret necessari per avviare il microgateway. Se hai bisogno di aiuto, consulta Configurare Edge Microgateway.
- Su Apigee Edge, crea un prodotto API e 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ù, vedi Configurazione del comportamento del percorso della risorsa. Vedi anche Creare prodotti API nella documentazione di Edge.
- Devi aggiungere il proxy edgemicro-auth al prodotto. Il deployment di questo proxy
è stato eseguito automaticamente quando hai eseguito
Su Apigee Edge, crea uno sviluppatore o, se vuoi, puoi utilizzarne uno esistente. Per informazioni, consulta Aggiungere sviluppatori utilizzando l'interfaccia utente di gestione perimetrale.
- Su Apigee Edge, crea un'app sviluppatore. Devi aggiungere all'app il prodotto API appena creato. Per assistenza, consulta Registrare un'app nell'interfaccia utente di gestione di Edge.
- Sulla macchina in cui è installato Edge Microgateway, esporta la seguente variabile di ambiente con il valore "1".
export EDGEMICRO_LOCAL_PROXY=1
- 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 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 sviluppatore che hai creato in precedenza. Apri l'app nell'interfaccia utente perimetrale, 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":"" }