Guida alle operazioni

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Come ottenere una chiave API

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

1. Accedi ad Apigee

  1. Accedi all'interfaccia utente di Apigee.
  2. Seleziona la stessa organizzazione utilizzata per eseguire il provisioning di Apigee Adapter per Envoy.

2. Creazione di uno sviluppatore

Puoi utilizzare uno sviluppatore esistente per i test o crearne uno nuovo come segue:

  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 il nome/l'indirizzo email dello sviluppatore che preferisci.

3. Creazione di un prodotto API

Segui l'esempio di creazione del prodotto riportato di seguito.

  1. Seleziona Pubblica > Prodotti API nel menu di navigazione laterale.
  2. Fai clic su +CREA.
  3. Compila la sezione Dettagli prodotto come segue. Nella tabella seguente sono indicati solo i campi obbligatori:
    Campo Valore Descrizione
    Nome httpbin-product Il nome univoco del prodotto API.
    Nome visualizzato httpbin product Il nome descrittivo che vuoi visualizzare nell'interfaccia utente o in altri contesti di visualizzazione.
    Accesso Public Ai fini di questo esempio, Pubblico è una buona scelta.
  4. Nella sezione Operazioni, fai clic su + AGGIUNGI UN'OPERAZIONE.
  5. Nella sezione Origine, seleziona Servizio remoto.
  6. Attiva/disattiva l'opzione Origine per poter digitare manualmente il nome di un servizio remoto nel campo Servizio remoto.
  7. Nel campo Servizio remoto, inserisci il nome di un servizio remoto. Si tratta di un servizio di destinazione a cui l'adattatore esegue il proxy delle richieste HTTP in entrata. Per scopi di test, utilizza httpbin.org o httpbin.default.svc.cluster.local con Kubernetes.

    Il pulsante di opzione Servizio remoto è selezionato, l'opzione di attivazione/disattivazione dell'inserimento manuale del testo è attivata e il servizio remoto httpbin.org è inserito nel campo Servizio remoto.

  8. Nella sezione Operazione, inserisci / per il percorso. Per informazioni sulle opzioni di percorso, consulta Configurare i percorsi delle risorse.
  9. Fai clic su SALVA per salvare l'operazione.
  10. Fai clic su SALVA per salvare il prodotto API.

Per saperne di più, consulta Gestire i prodotti API.

4. Creazione di un'app sviluppatore

L'app per sviluppatori contiene la chiave API necessaria per effettuare chiamate proxy API tramite l'adattatore.

  1. Seleziona Pubblica app nel menu di navigazione laterale.
  2. Fai clic su + App.
  3. Compila la sezione Dettagli dell'app come segue. Nella tabella seguente sono indicati solo i campi obbligatori:
    4. Nome httpbin-app
    Developer Seleziona lo sviluppatore che hai creato in precedenza o scegli uno qualsiasi dall'elenco.
  4. Nella sezione Credenziali, fai clic su + Aggiungi prodotto e seleziona il prodotto appena configurato: httpbin-product.
  5. Fai clic su Crea.
  6. In Credenziali, fai clic su Mostra accanto a Chiave.
  7. Copia il valore della chiave consumer. Questo valore è la chiave API che utilizzerai per effettuare chiamate API al servizio httpbin tramite l'adattatore Apigee per Envoy.

Utilizzo dell'autenticazione basata su JWT

Puoi utilizzare un token JWT per effettuare chiamate proxy API autenticate anziché 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 un ambiente Apigee ibrido, puoi utilizzare questo comando per creare il secret Kubernetes per contenere i token JWT.

Panoramica

La verifica e l'autenticazione JWT vengono gestite da Envoy utilizzando il JWT Authentication Filter.

Una volta autenticato, il filtro ext-authz di Envoy invia le intestazioni della richiesta e il JWT a apigee-remote-service-envoy. Corrisponde ai claim api_product_list e scope del JWT ai prodotti API Apigee per autorizzarlo rispetto al target della richiesta.

Creazione di token JWT Apigee

I token JWT di 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, puoi utilizzare l'endpoint del token OAuth standard. Esempio di curl:

curl https://org-env.apigee.net/remote-token/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, devi semplicemente passarlo a Envoy nell'intestazione Authorization. Esempio:

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

Errore del token JWT

Rifiuto di Envoy

Se Envoy rifiuta il token, potresti visualizzare un messaggio simile al seguente:

Jwks remote fetch has 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 quando hai installato il proxy Apigee. Dovresti essere in grado di chiamare direttamente l'URI con una chiamata GET e ricevere una risposta JSON valida.

Esempio:

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

Altri messaggi di Envoy potrebbero avere il seguente aspetto:

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

Si tratta di requisiti nella configurazione di Envoy che potresti dover modificare.

Ispezionare un token

Puoi utilizzare l'interfaccia a riga di comando per controllare 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

Vedi Chiave API valida non funziona.

Utilizzare il tuo provider di identità

Per impostazione predefinita, Apigee Adapter for Envoy utilizza il proxy API remote-token come servizio di provider di identità per autenticare le applicazioni client e fornire token JWT in base al tipo di concessione delle credenziali client OAuth 2.0. In alcuni casi, tuttavia, potresti non essere in grado di utilizzare il proxy remote-token. Se devi utilizzare un provider di identità diverso da quello fornito da Apigee, puoi configurare l'adattatore in modo che utilizzi un altro provider di identità. Per informazioni dettagliate su questo caso d'uso del provider di identità non Apigee e sulla configurazione richiesta, consulta questo articolo della community Apigee: Utilizzare il tuo provider di identità con l'adattatore Apigee Envoy.

Logging

Puoi regolare il livello di logging nel servizio $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Tutto il logging viene inviato a stderr.

Elemento Obbligatorio Descrizione
-l, --log-level Livelli validi: debug, info, warn, error. Regola il livello di registrazione. Valore predefinito: info
-j, --json-log Emette l'output del log come record JSON.

Envoy fornisce la registrazione. Per ulteriori informazioni, consulta i seguenti link alla documentazione di Envoy:

Modifica del nome del secret del criterio

Un segreto Kubernetes di cui è stato eseguito il deployment nel cluster contiene le credenziali di cui l'adattatore ha bisogno 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 modificare 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. Modifica 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 l'invio di host specifici 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.

Dati di Envoy

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

Dati e analisi di Istio

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

Apigee Analytics

Apigee Remote Service for Envoy invia le statistiche sulle richieste ad Apigee per l'elaborazione di analisi. Apigee registra queste richieste sotto il nome del prodotto API associato.

Per informazioni su Apigee Analytics, consulta la panoramica dei servizi di analisi.

Supporto dell'ambiente multi-tenant

Ora puoi consentire all'adattatore di gestire più ambienti in un'organizzazione Apigee. Questa funzionalità ti consente di utilizzare un Apigee Adapter for Envoy associato a un'organizzazione Apigee per gestire più ambienti. Prima di questa modifica, un'adattatore era sempre associato a un ambiente Apigee.

Per configurare il supporto di più ambienti, modifica il valore di tenant:env_name in "*" nel file config.yaml. Ad esempio:

  1. Apri il file config.yaml in un editor.
  2. Modifica il valore di tenant.env_name in "*". Ad esempio: 
    apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://apitest.mydomain.net/remote-service
      org_name: my-org
      env_name: "*""
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://apitest.mydomain.net/remote-token/token
  3. Salva il file.
  4. Applica il file: 
    kubectl apply -f $CLI_HOME/config.yaml

Quando configuri la modalità multiambiente, devi anche configurare Envoy in modo che invii un valore di ambiente appropriato all'adattatore aggiungendo i seguenti metadati nella sezione virtual_hosts:routes del file envoy-config.yaml. Ad esempio:

  1. Genera il file envoy-config.yaml utilizzando l'interfaccia a riga di comando. Ad esempio: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  2. Apri il file generato (si chiama envoy-config.yaml).
  3. Aggiungi i seguenti metadati nella sezione virtual_host o routes del file: 
    typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

    L'esempio seguente illustra la configurazione di un virtual_host con più route definiti, in cui ogni route invia il traffico a un ambiente specifico: 

    filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod
  4. Ripeti l'ultimo passaggio per aggiungere altri ambienti, se necessario.
  5. Salva il file e applicalo.

Acquisizione dei dati per i report personalizzati

L'adattatore supporta il passaggio dei metadati di Envoy alla funzionalità di acquisizione dei dati di Apigee, che invia i dati acquisiti nelle variabili specificate ad Apigee Analytics per l'utilizzo nei report personalizzati. Questa funzionalità offre una funzionalità simile al criterio di acquisizione dei dati di Apigee.

Per utilizzare questa funzionalità:

  1. Crea una risorsa REST del raccoglitore dati.
  2. Definisci le variabili di acquisizione dei dati utilizzando l'API Datacollectors di Apigee.
  3. Se non l'hai ancora fatto, genera il file envoy-config.yaml utilizzando l'interfaccia a riga di comando. Ad esempio: 
    $CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs
  4. Apri il file generato (si chiama envoy-config.yaml).
  5. Utilizza un filtro Envoy per impostare i valori per le variabili personalizzate nello spazio dei nomi envoy.filters.http.apigee.datacapture. Ad esempio, puoi utilizzare un filtro Intestazione in metadati o un filtro Lua. Per ulteriori informazioni su questi filtri, consulta Intestazione a metadati e Lua.

    I nomi delle variabili personalizzate devono essere formattati come dc.XXXXX.

    Esempio di filtro da intestazione a metadati: 

     - name: envoy.filters.http.header_to_metadata
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
    request_rules:
      - header: "Host"
        on_header_present:
          metadata_namespace: envoy.filters.http.apigee.datacapture
          key: dc.host  # host (without the prefix) also works
          type: STRING
        remove: false

    Esempio di filtro Lua: 

    - name: envoy.filters.http.lua
  typed_config:
    "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
    inline_code: |
      function envoy_on_request(request_handle)
        metadata = request_handle:streamInfo():dynamicMetadata()
        metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
      end
  6. Aggiungi il filtro desiderato al file. Vedi gli esempi qui sotto.
  7. Salva il file e applicalo.

Configurazione di mTLS tra l'adattatore e il runtime Apigee

Puoi fornire certificati TLS lato client nella sezione tenant del file config.yaml dell'adattatore per utilizzare mTLS tra l'adattatore e il runtime Apigee. Questa modifica si applica a tutte le piattaforme Apigee supportate. Inoltre, abilita mTLS per le analisi per la piattaforma Apigee Edge for Private Cloud. Ad esempio: 

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false