Panoramica dei callout

Service Extensions ti consente di effettuare un callout dai proxy di networking. Le estensioni callout sono supportate dalla maggior parte dei bilanciatori del carico delle applicazioni. Le estensioni callout sono supportate anche da Secure Web Proxy (in anteprima).

Flusso di dati dei callout

Un proxy di rete comunica con un callout utilizzando uno dei seguenti protocolli gRPC Envoy:

• Il protocollo di trattamento esterno o ext_proc.

  Questo protocollo è supportato per le estensioni di route, traffico e autorizzazione e viene utilizzato per impostazione predefinita.

  Il protocollo ext_proc consente al servizio di estensione di rispondere agli eventi nel ciclo di vita di una richiesta HTTP esaminando e modificando le intestazioni o il corpo della richiesta.

• Il protocollo di autorizzazione esterna o ext_authz.

  Questo protocollo è supportato solo per le estensioni di autorizzazione. Il supporto per ext_authz è in anteprima.

  Il protocollo ext_authz delega le decisioni di autorizzazione per le richieste in entrata a un servizio esterno indipendente. Questa API consente al servizio di estensione di rispondere agli eventi nel ciclo di vita di una richiesta HTTP per una decisione di autorizzazione complessa esaminando le intestazioni o i metadati della richiesta.

  Puoi specificare questo protocollo con l'opzione wireFormat quando configuri un'estensione di autorizzazione.

Puoi eseguire il deployment di questi servizi di estensione su istanze di macchine virtuali (VM) o su GKE e configurare un gruppo di istanze o un gruppo di endpoint di rete (NEG) per rappresentare gli endpoint di questi servizi.

Scenario di deployment di esempio

Il seguente diagramma mostra uno scenario di deployment di esempio. Puoi eseguire il deployment del servizio di backend callout con un server gRPC su una risorsa di calcolo gestita dall'utente, ad esempio un'istanza VM o un cluster Google Kubernetes Engine (GKE), e rappresentarlo al bilanciatore del carico come un normale servizio di backend.

I bilanciatori del carico delle applicazioni inviano callout di Service Extensions per chiamare i servizi di backend (fai clic per ingrandire).

Come funzionano i callout con ext_proc

Di seguito è riportata una versione abbreviata dell'API gRPC ext_proc.

// The gRPC API to be implemented by the external processing server
service ExternalProcessor {
  rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) {
  }
}

// Envoy sets one of these fields depending on the processing stage.
message ProcessingRequest {
  oneof request {
    HttpHeaders request_headers = 2;
    HttpHeaders response_headers = 3;
    HttpBody request_body = 4;
    HttpBody response_body = 5;
  }
}

message ProcessingResponse {
  oneof response {
    HeadersResponse request_headers = 1;
    HeadersResponse response_headers = 2;
    BodyResponse request_body = 3;
    BodyResponse response_body = 4;

    ImmediateResponse immediate_response = 7;
  }
}

Dopo aver ricevuto le intestazioni per una richiesta HTTP, i proxy del bilanciatore del carico delle applicazioni e di Secure Web Proxy inviano il messaggio ProcessingRequest al servizio di estensione con il campo request_headers impostato sulle intestazioni HTTP del client.

Il servizio di estensione deve rispondere al messaggio ProcessingRequest con un messaggio ProcessingResponse corrispondente che contenga eventuali modifiche configurate alle intestazioni o al corpo del messaggio ProcessingRequest. In alternativa, il servizio può impostare il campo immediate_response per fare in modo che il proxy di rete termini l'elaborazione della richiesta e invii la risposta specificata al client.

Per gli eventi REQUEST_HEADER e RESPONSE_HEADER, il servizio di estensione può manipolare le intestazioni HTTP nella richiesta o nella risposta. Il servizio può aggiungere, modificare o eliminare le intestazioni impostando il campo request_headers o response_headers nel messaggio ProcessingResponse in modo appropriato. Utilizza il campo raw_value per le intestazioni.

Le estensioni del traffico consentono di modificare le intestazioni e il corpo di richieste e risposte. Il server delle estensioni può eseguire l'override dinamico della modalità di elaborazione e consentire l'attivazione o la disattivazione dell'estensione per le fasi successive dell'elaborazione della richiesta. I bilanciatori del carico non rivalutano le regole di routing dopo aver chiamato un'estensione del traffico.

Le estensioni perimetrali, di autorizzazione e di route supportano solo le intestazioni HTTP. Queste estensioni non possono esaminare o modificare i corpi HTTP.

Per le estensioni di itinerario e traffico, i callout possono essere eseguiti in modo asincrono quando observabilityMode per l'estensione è impostato su true e la modalità di elaborazione del corpo è STREAMED (impostazione predefinita). Le chiamate al backend dell'estensione vengono eseguite in modo asincrono, senza mettere in pausa l'elaborazione della richiesta in corso. Le risposte, se presenti, vengono ignorate.

Come funzionano i callout con ext_authz

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

L'API ext_authz supporta solo le estensioni callout di autorizzazione.

Di seguito è riportata una versione abbreviata dell'API.

// A generic interface for performing authorization checks on incoming
// requests to a networked service.
service Authorization {
  // Performs an authorization check based on the attributes associated with
  // the incoming request and return status.
  rpc Check(CheckRequest) returns (CheckResponse) {
  }
}

message CheckRequest {
  // The request attributes.
  AttributeContext attributes = 1;
}

message CheckResponse {
  google.rpc.Status status = 1;
  oneof http_response {
    DeniedHttpResponse denied_response = 2;
    OkHttpResponse ok_response = 3;
  }
  google.protobuf.Struct dynamic_metadata = 4;
}

Dopo aver ricevuto le intestazioni per una richiesta HTTP, il bilanciatore del carico invia il messaggio CheckRequest al servizio di estensione.

Il servizio di estensione deve rispondere al messaggio CheckRequest con un messaggio CheckResponse corrispondente contenente le seguenti informazioni:

• status: indica lo stato. OK indica che la richiesta è consentita. Qualsiasi altro stato indica che la richiesta è stata rifiutata.

• denied_response o ok_response: indica se la risposta è consentita o negata. Questo campo è accompagnato dagli attributi di risposta HTTP correlati per un controllo dell'autorizzazione.

  • Il campo ok_response viene utilizzato quando il servizio di autorizzazione consente la richiesta. Il servizio può modificare, aggiungere o rimuovere qualsiasi intestazione della richiesta originale e aggiornare le intestazioni della risposta HTTP inviate al client. Utilizza il campo raw_value per le intestazioni.

  • Il campo denied_response viene utilizzato quando il servizio di autorizzazione nega la richiesta. Il servizio può aggiornare le intestazioni della risposta HTTP inviate al client.

  Se il servizio di estensione restituisce un nome o un valore di intestazione non consentito tramite il messaggio CheckResponse, la richiesta viene rifiutata con il codice di stato 500 Internal Error. Per informazioni sulle intestazioni non consentite, vedi Limitazioni relative alla manipolazione delle intestazioni.

• dynamic_metadata: include metadati facoltativi da utilizzare con le estensioni chiamate dopo l'estensione di autorizzazione, ad esempio le estensioni di traffico.

Modalità di elaborazione del corpo

Per le estensioni che supportano l'elaborazione del corpo, puoi configurare una delle due modalità di invio seguenti per l'elaborazione del corpo della richiesta e della risposta impostando il valore dei campi request_body_send_mode o response_body_send_mode, rispettivamente.

La modalità predefinita è STREAMED, consigliata per la maggior parte dei casi d'uso.

Modalità	Descrizione	Eventi supportati richiesti	Estensioni supportate
STREAMED	Le chiamate vengono eseguite in modalità streaming. Questa impostazione predefinita viene utilizzata anche se la modalità non è impostata. Il proxy invia blocchi del corpo al servizio di estensione e si aspetta una singola risposta per blocco. L'estensione può inviare nuovamente i blocchi modificati, confermare i blocchi senza modifiche o eliminarli. Il proxy invia solo una quantità limitata di dati alla volta. Pertanto, il servizio di estensione deve riconoscere i chunk il prima possibile. Sebbene la modalità body non possa essere modificata in modo dinamico, un server di estensione avanzato può selezionare dinamicamente gli eventi HTTP futuri da ricevere. Restituendo l'opzione ext_proc mode_override durante una richiesta di intestazioni, un server di callout può attivare o disattivare eventi futuri di intestazioni, corpo o trailer.	Deve includere REQUEST_BODY per le richieste o RESPONSE_BODY per le risposte.	Estensioni del traffico (sia per le richieste che per le risposte).
FULL_DUPLEX_STREAMED	Le chiamate vengono eseguite in modalità full duplex. Il proxy invia i chunk man mano che arrivano e non li memorizza nel buffer. Poiché non è presente buffering, il proxy è meno sensibile alla latenza dell'estensione. Il proxy può ricevere tutti i blocchi di risposta necessari. I blocchi di risposta vengono scollegati dai blocchi inviati dal proxy. I chunk successivi vengono inviati per l'elaborazione quando arrivano al proxy, senza attendere che i chunk e gli eventi precedenti vengano elaborati completamente. L'estensione può memorizzare nel buffer, modificare e ricomporre liberamente i contenuti del corpo. Se l'estensione non invia di nuovo i contenuti del corpo, l'estensione successiva nella catena riceve un corpo vuoto. L'opzione ext_proc mode_override non è applicabile e la modalità non può essere modificata in modo dinamico. Avviso:il proxy si apre fino all'elaborazione del primo blocco di dati del corpo. Ciò significa che fail-open gestisce qualsiasi problema relativo alla connessione all'estensione o alla gestione delle intestazioni, ma gli errori successivi a questo punto vengono chiusi e propagati all'utente finale.	Devono includere REQUEST_BODY e REQUEST_TRAILERS per le richieste o RESPONSE_BODY e RESPONSE_TRAILERS per le risposte.	Estensioni del traffico (sia per le richieste che per le risposte). Estensioni route (per le richieste).

Backend supportati per i servizi di backend di callout gestiti dall'utente

Puoi ospitare le estensioni callout gestite dall'utente su un servizio di backend che utilizza uno dei seguenti tipi di backend che eseguono servizi gRPC Envoy:

• Tutti i backend dei gruppi di istanze gestite e non gestite
• Tutti i NEG a livello di zona
• Tutti i NEG di connettività ibrida
• NEG Private Service Connect che puntano ai servizi VPC
• NEG serverless che puntano ai servizi Cloud Run

Nota: quando ospiti l'estensione su Cloud Run, il servizio Cloud Run deve rimanere in ascolto su una porta gRPC in testo non crittografato. Il servizio Cloud Run deve essere configurato per accettare il traffico HTTP/2 e deve consentire l'accesso non autenticato.

Ottimizzazioni consigliate per i callout

L'integrazione di un'estensione nel percorso di elaborazione comporta una latenza aggiuntiva per richieste e risposte. Ogni tipo di dati elaborati dal servizio di estensione, inclusi intestazioni della richiesta, corpo della richiesta, intestazioni della risposta e corpo della risposta, a seconda dei casi, aggiunge latenza.

Valuta le seguenti ottimizzazioni per ridurre al minimo la latenza:

• Esegui il deployment dei callout nelle stesse zone del normale servizio di backend di destinazione per il proxy.

  Quando utilizzi un bilanciatore del carico delle applicazioni interno tra regioni, posiziona i backend del servizio di estensione nella stessa regione delle subnet solo proxy del bilanciatore del carico.

• Quando utilizzi un bilanciatore del carico delle applicazioni esterno globale, posiziona i backend del servizio di callout nelle regioni geografiche in cui si trovano le VM di destinazione del bilanciatore del carico normale, i carichi di lavoro GKE e le funzioni Cloud Run.

• Se possibile, configura l'estensione in modo che elabori solo i dati che ti servono. Ad esempio, per modificare solo le intestazioni delle richieste per le estensioni di itinerario e traffico, imposta il campo supported_events nell'estensione su REQUEST_HEADERS.

Limitazioni dei callout

Questa sezione elenca alcune limitazioni relative ai callout.

Limitazioni relative alla manipolazione delle intestazioni

Non puoi modificare alcune intestazioni. Di seguito sono riportate le limitazioni relative alla manipolazione dell'intestazione:

• La manipolazione delle intestazioni non è supportata per le seguenti intestazioni:

  • X-user-IP
  • CDN-Loop
  • Intestazioni che iniziano con X-Forwarded, X-Google, X-GFE o X-Amz-
  • connection
  • keep-alive
  • transfer-encoding, te
  • upgrade
  • proxy-connection, proxy-authenticate, proxy-authorization
  • trailers

  Per le estensioni di traffico e autorizzazione, la manipolazione degli header non è supportata anche per: :method, :authority, :scheme o header host.

• Quando un server gRPC specifica i valori delle intestazioni in HeaderMutation, il campo value viene ignorato.

Limitazioni con l'elaborazione del corpo

Di seguito sono riportate le limitazioni relative ai client e ai backend HTTP/1.1 per quanto riguarda il corpo del messaggio, che si applicano a ext_proc ma non a ext_authz.

• Quando configuri REQUEST_BODY o RESPONSE_BODY per un'estensione, se il proxy riceve una richiesta corrispondente, rimuove l'intestazione Content-Length dalla risposta e passa alla codifica del corpo in blocchi.

• Durante lo streaming di un corpo del messaggio al server ext_proc, alla fine il proxy potrebbe inviare un messaggio ProcessingRequest di coda con un corpo vuoto con end_stream impostato su true per indicare che lo stream è terminato.

Altre limitazioni

Di seguito sono riportate le limitazioni relative ai messaggi di risposta gRPC:

• La dimensione massima di un messaggio di risposta è 128 kB. Se un messaggio ricevuto supera questo limite, lo stream viene chiuso con un errore RESOURCE_EXHAUSTED.

• Il servizio di backend di callout non può utilizzare le policy Cloud Armor, IAP o Cloud CDN.

• Il servizio di backend callout deve utilizzare HTTP/2 come protocollo.

• Per le estensioni di autorizzazione, il bilanciatore del carico non inoltra alcun corpo della richiesta al servizio di backend di callout.

• Per le estensioni di route, il servizio di backend callout non può eseguire l'override della modalità di elaborazione dello stream ext_proc.

Passaggi successivi

• Configura un servizio di backend di callout gestito dall'utente

  Un servizio di backend di callout è un prerequisito per la configurazione di route, autorizzazione ed estensioni del traffico gestite dall'utente tramite i callout.

• Configurare un'estensione di autorizzazione

• Configurare un'estensione per Secure Web Proxy

• Configurare un'estensione del traffico

• Configurare un'estensione per chiamare un servizio Google