Guida operativa

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Come ottenere una chiave API

L'esempio seguente spiega come ottenere una chiave API da utilizzare per convalidare le chiamate API a un servizio di destinazione inviato tramite proxy tramite Apigee Adapter per Envoy.

1. Accedi ad Apigee

  1. Apri la UI di Apigee in un browser.
  2. Una volta nella UI, seleziona la stessa organizzazione che hai utilizzato per configurare Apigee Adapter for Envoy.

2. Creazione di uno sviluppatore

Puoi utilizzare uno sviluppatore esistente per i test oppure crearne uno nuovo procedendo nel seguente modo:

  1. Seleziona Pubblica > Sviluppatori nel menu di navigazione laterale.
  2. Fai clic su + Sviluppatore.
  3. Compila la finestra di dialogo per creare un nuovo sviluppatore. Puoi utilizzare qualsiasi nome/indirizzo email dello sviluppatore che desideri.

3. Creazione di un prodotto API

Segui l'esempio di creazione del prodotto fornito di seguito. Vedi anche Informazioni sui prodotti API.

  1. Seleziona Pubblica > Prodotti API nel menu di navigazione laterale.
  2. Fai clic su + Prodotto API.
  3. Compila la pagina Dettagli prodotto come segue. Non fare clic su Salva fino a quando non ti viene chiesto di farlo.
    4. Campo Valore
    Nome httpbin-product
    Nome visualizzato httpbin product
    Ambiente your_environment

    Impostalo sull'ambiente che hai utilizzato quando hai eseguito il provisioning di Apigee Adapter per Envoy con apigee-remote-service-cli.

    Accesso Private
    Quota 5 richieste ogni minuto

    Vedi anche Informazioni sulla configurazione del prodotto API.

  4. Nella sezione Destinazioni di servizio remoto Apigee, fai clic su Aggiungi un target di servizio remoto Apigee.
  5. Nella finestra di dialogo di destinazione del servizio remoto Apigee, aggiungi i seguenti valori:
    Attributo Valore Descrizione
    Nome destinazione Inserisci il nome del servizio di destinazione. Ad esempio: httpbin.org L'endpoint di destinazione davanti al proxy Envoy.
    proxy API remote-service Il proxy remote-service di cui è stato eseguito il provisioning su Apigee durante l'installazione dell'adattatore Envoy.
    Percorso Inserisci un /resource_path che corrisponda a un percorso specifico. Ad esempio: /httpbin. Il percorso di richiesta per trovare una corrispondenza nell'endpoint di destinazione. Le chiamate proxy API a questo percorso corrisponderanno a questo prodotto API.
  6. Fai clic su Salva.

4. Creazione di un'app sviluppatore

  1. Seleziona Pubblica > App nel menu di navigazione laterale.
  2. Fai clic su + App.
  3. Compila la pagina dell'app sviluppatore come segue. Non salvare finché non ti viene chiesto di farlo.
    4. Nome httpbin-app
    Nome visualizzato httpbin app
    Developer Seleziona lo sviluppatore che hai creato in precedenza o scegline uno che preferisci dall'elenco.
  4. Dopodiché, aggiungi due prodotti all'app:
    1. Innanzitutto, nella sezione Credenziali, fai clic su + Aggiungi prodotto e seleziona il prodotto appena configurato: httpbin-product.
    2. Quindi, aggiungi il prodotto remote-service. Questo prodotto è stato creato automaticamente quando hai eseguito il provisioning di Apigee.
  5. Fai clic su Crea.
  6. In Credenziali, fai clic su Mostra accanto a Chiave.
  7. Copia il valore della chiave utente. Questo valore è la chiave API che utilizzerai per effettuare chiamate API al servizio httpbin.

Informazioni sui prodotti API

I prodotti API sono il punto di controllo principale per il servizio remoto Apigee. Quando crei un prodotto API e lo associ a un servizio di destinazione, viene creato un criterio che verrà applicato a tutte le richieste che verranno gestite da Apigee Adapter per Envoy.

Definizione del prodotto API

Quando definisci un prodotto API in Apigee, puoi impostare un numero di parametri che verranno utilizzati per valutare le richieste:

  • Target
  • Percorso richiesta
  • Quota
  • Ambiti OAuth

Target di servizio remoti

La definizione del prodotto API verrà applicata a una richiesta se corrisponde sia all'associazione di destinazione (ad esempio, httpbin.org) sia al percorso di richiesta (ad esempio, /httpbin). Un elenco di potenziali target viene archiviato come attributo nel prodotto API.

Per impostazione predefinita, il servizio remoto Apigee controlla l'intestazione :authority (host) speciale di Envoy rispetto al suo elenco di destinazioni; tuttavia, può essere configurato per l'utilizzo di altre intestazioni.

Percorso risorsa API

Il percorso inserito corrisponde in base alle seguenti regole:

  • Una barra (/) da sola corrisponde a qualsiasi percorso.
  • * è valido ovunque e corrisponde all'interno di un segmento (tra le barre).
  • ** è valido alla fine e corrisponde a qualsiasi cosa alla fine della riga.

Quota

Una quota specifica il numero di messaggi di richiesta che un'app può inviare a un'API nel corso di un'ora, un giorno, una settimana o un mese. Quando un'app raggiunge il limite di quota, le chiamate API successive vengono rifiutate.

Casi d'uso relativi alle quote

Le quote consentono di applicare in modo forzato il numero di richieste che un client può effettuare a un servizio in un determinato periodo di tempo. Le quote vengono spesso utilizzate per far rispettare contratti aziendali o SLA con sviluppatori e partner, anziché per la gestione operativa del traffico. Ad esempio, è possibile utilizzare una quota per limitare il traffico per un servizio gratuito, consentendo l'accesso completo ai clienti paganti.

La quota è definita in un prodotto API

I parametri di quota sono configurati nei prodotti API. Ad esempio, quando crei un prodotto API, puoi impostare facoltativamente il limite di quota, l'unità di tempo e l'intervallo consentiti.

Imposta il limite di quota, l'unità di tempo e l'intervallo consentiti per un prodotto API.

Poiché le chiavi API corrispondono ai prodotti API, ogni volta che una chiave API viene verificata, il contatore di quota appropriato può essere ridotto (se è definita una quota nel prodotto associato).

A differenza del runtime Apigee, le quote immesse nella definizione del prodotto vengono applicate automaticamente dal servizio remoto Apigee. Se la richiesta è autorizzata, verrà conteggiata ai fini della quota consentita.

Dove vengono mantenute le quote

Le quote vengono gestite e controllate localmente dal processo del servizio remoto e gestite in modo asincrono con il runtime Apigee. Ciò significa che le quote non sono precise e potrebbero essere superate se hai più di un servizio remoto che mantiene la quota. Se la connessione al runtime Apigee viene interrotta, la quota locale continuerà come quota autonoma fino a quando non potrà riconnettersi al runtime Apigee.

Ambiti OAuth

Se utilizzi token JWT, puoi limitarli a sottoinsiemi degli ambiti OAuth consentiti. Gli ambiti assegnati al token JWT emesso verranno verificati in base agli ambiti del prodotto API.

Informazioni sulle app sviluppatore

Dopo aver configurato i tuoi prodotti API, dovrai creare un'app associata a uno sviluppatore. L'app consente a un client di accedere ai prodotti API associati con una chiave API o un token JWT.

Utilizzo dell'autenticazione basata su JWT

Puoi utilizzare un token JWT per effettuare chiamate proxy API autenticate invece di utilizzare una chiave API. Questa sezione spiega come utilizzare il comando apigee-remote-service-cli token per creare, ispezionare e ruotare i token JWT. Per l'ambiente ibrido Apigee, puoi utilizzare questo comando per creare un secret Kubernetes in cui inserire i JWT.

Panoramica

La verifica e l'autenticazione JWT vengono gestite da Envoy utilizzando il suo filtro di autenticazione JWT.

Una volta eseguita l'autenticazione, il filtro ext-authz di Envoy invia le intestazioni della richiesta e il JWT a apigee-remote-service-envoy. Corrisponde alle rivendicazioni api_product_list e scope di JWT nei confronti dei prodotti API Apigee per autorizzarla in base alla destinazione della richiesta.

Creazione di token JWT Apigee in corso...

I token JWT Apigee possono essere creati utilizzando l'interfaccia a riga di comando:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

In alternativa, utilizzando l'endpoint del token OAuth standard. Esempio di Curl:

curl https://org-env.apigee.net/remote-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

Utilizzo del token JWT

Una volta ottenuto il token, è sufficiente passarlo a Envoy nell'intestazione Autorizzazione. Esempio:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Errore del token JWT

Rifiuto di Envoy

Se Envoy rifiuta il token, potrebbe essere visualizzato un messaggio simile al seguente:

Jwks remote fetch is failed

In questo caso, assicurati che la configurazione di Envoy contenga un URI valido nella sezione remote_jwks, che sia raggiungibile da Envoy e che tu abbia impostato correttamente i certificati al momento dell'installazione del proxy Apigee. Dovresti essere in grado di chiamare l'URI direttamente con una chiamata GET e ricevere una risposta JSON valida.

Esempio:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Altri messaggi da Envoy possono avere il seguente aspetto:

  • "I segmenti di pubblico in Jwt non sono consentiti"
  • "L'emittente Jwt non è configurato"

Si tratta dei requisiti della tua configurazione Envoy che potresti dover modificare.

Ispeziona un token

Puoi utilizzare l'interfaccia a riga di comando per ispezionare il token. Esempio

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

o 

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Debug

Consulta l'articolo Errori relativi a una chiave API valida.

Logging

Puoi modificare il livello di logging nel servizio $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Tutti i log vengono inviati a stderr.

Elemento Obbligatorio Descrizione
-l, --log-level Livelli validi: debug, informazioni, avviso, errore. Regola il livello di logging. Valore predefinito: info
-j, --json-log Emette l'output di log come record JSON.

Envoy fornisce il logging. Per ulteriori informazioni, consulta i seguenti link alla documentazione di Envoy:

Modifica del nome del secret del criterio

Un secret Kubernetes di cui è stato eseguito il deployment nel cluster contiene le credenziali necessarie all'adattatore per autenticare la comunicazione con il proxy del servizio remoto. Questo secret richiede un punto di montaggio del volume, che è configurabile. Per impostazione predefinita, il punto di montaggio è /policy-secret. Per cambiare il punto di montaggio:

  1. Esegui questo comando: 
    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

    Ad esempio: 

    $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point
  2. Apri $CLI_HOME/samples/apigee-envoy-adapter.yaml in un editor.
  3. Cambia il nome del punto di montaggio con il nuovo nome: 
    volumeMounts:
  - mountPath: /config
    name: apigee-remote-service-envoy
    readOnly: true
  - mountPath: /opt/apigee/tls
    name: tls-volume
    readOnly: true
  - mountPath: /my-mount-point
    name: policy-secret
    readOnly: true
  4. Salva il file e applicalo al mesh di servizi: 
    kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Utilizzo di un proxy di rete

Un proxy HTTP può essere inserito utilizzando le variabili di ambiente HTTP_PROXY e HTTPS_PROXY nell'ambiente del file binario apigee-remote-service-envoy. Quando le utilizzi, la variabile di ambiente NO_PROXY può essere utilizzata anche per escludere host specifici dall'invio tramite il proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

Ricorda che il proxy deve essere raggiungibile da apigee-remote-service-envoy.

Informazioni su metriche e analisi

Un endpoint delle metriche Prometheus è disponibile all'indirizzo :5001/metrics. Puoi configurare questo numero di porta. Consulta File di configurazione.

Analisi di Envoy

I seguenti link forniscono informazioni su come ottenere i dati di analisi del proxy Envoy:

Analisi Istio

I seguenti link forniscono informazioni su come ottenere i dati di analisi del proxy Envoy:

Analisi Apigee

Il servizio remoto Apigee per Envoy invia statistiche delle richieste ad Apigee per l'elaborazione delle analisi. Apigee segnala queste richieste sotto il nome del prodotto API associato.

Per informazioni sull'analisi di Apigee, consulta la panoramica dei servizi di analisi.