Configurare un'estensione di route

Service Extensions consente ai bilanciatori del carico delle applicazioni supportati di utilizzare plug-in o inviare callout ai servizi di backend per inserire l'elaborazione personalizzata nel percorso di elaborazione. Le estensioni di route vengono eseguite nel percorso di elaborazione delle richieste quando il bilanciatore del carico riceve le intestazioni delle richieste e prima di valutare la mappa URL. Questa pagina descrive come configurare le estensioni di route.

Per una panoramica delle estensioni del bilanciatore del carico delle applicazioni, consulta la panoramica delle estensioni Cloud Load Balancing.

Un'estensione di route per un bilanciatore del carico delle applicazioni punta alle seguenti risorse:

  • Una regola di forwarding a cui collegarsi
  • Un plug-in o un servizio di backend di callout i cui backend eseguono l'API gRPC ext_proc

Un'estensione di route raggruppa i servizi di estensione correlati in una catena. Puoi configurare sia i plug-in sia i callout nella stessa catena di estensioni. La catena di estensioni seleziona il traffico su cui agire utilizzando le condizioni di corrispondenza del Common Expression Language (CEL). Il bilanciatore del carico valuta una richiesta in base alle condizioni di corrispondenza per una catena in modo sequenziale. Quando una richiesta corrisponde alle condizioni definite da una catena, tutte le estensioni della catena agiscono sulla richiesta. Solo una catena corrisponde a una determinata richiesta.

L'estensione fa riferimento alla regola di forwarding del bilanciatore del carico a cui collegarsi. Dopo aver configurato la risorsa, il bilanciatore del carico inizia a inviare le richieste corrispondenti ai servizi di estensione.

Per informazioni sui limiti relativi alle estensioni del bilanciatore del carico delle applicazioni, consulta la pagina Quote e limiti.

Configurare utilizzando i plug-in

Questa sezione utilizza un esempio per mostrare come configurare un'estensione di route utilizzando un plug-in che riscrive l'intestazione della richiesta :host in service-extensions.com quando il percorso corrisponde a /extensions. L'host precedente e l'host appena configurato vengono mappati ai servizi di backend in regioni diverse, il che dimostra il comportamento di routing.

Tutte le risorse di estensione che fanno riferimento a un determinato plug-in devono essere dello stesso tipo. Inoltre, le estensioni devono avere lo stesso schema di bilanciamento del carico. Non puoi configurare le estensioni Cloud Load Balancing con plug-in già utilizzati nelle estensioni Media CDN.

Prima di iniziare

  1. Crea un plug-in che contenga il tuo codice personalizzato.

  2. Crea e configura un bilanciatore del carico delle applicazioni che supporti i plug-in di estensione delle route.

    Segui le istruzioni riportate nella pagina Configura un bilanciatore del carico delle applicazioni interno tra regioni con backend di gruppi di istanze VM per tutti i passaggi, tranne i seguenti:

    • Assegna al servizio di backend il nome service-one.
    • Punta service-one a un'istanza di macchina virtuale (VM) nella regione A.
    • Punta gl7-gilb-url-map a service-one per impostazione predefinita.

  3. Configura un servizio di backend aggiuntivo, service-two, e indirizzalo a una VM nella regione B.

  4. Alla mappa URL, aggiungi un matcher di percorso che rimandi a service-two. Utilizza il comando gcloud compute url-maps add-path-matcher con i seguenti valori di esempio:

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

  5. Configura un modo per inviare richieste di test al tuo servizio (ad esempio eseguendo curl). Se utilizzi un bilanciatore del carico interno, crea una VM client per il test.

Configurare un'estensione di route utilizzando un plug-in

  1. Controlla il comportamento prima che venga configurata un'estensione.

    1. Verifica che una richiesta senza un percorso esplicito venga inviata alla regione A:

      curl FORWARDING_RULE_IP

      Sostituisci FORWARDING_RULE_IP con l'indirizzo IP della regola di forwarding. Per trovare l'indirizzo IP, utilizza il comando gcloud compute forwarding-rules describe.

      L'output è simile al seguente e indica che la pagina viene servita da una VM in region A:

      Page served from region-A-vm

    2. Verifica che non ci sia alcuna corrispondenza per /extensions nella mappa URL:

      curl FORWARDING_RULE_IP/extensions

      Sostituisci FORWARDING_RULE_IP con l'indirizzo IP della regola di forwarding. Per trovare l'indirizzo IP, utilizza il comando gcloud compute forwarding-rules describe.

      L'output indica che non esiste alcuna corrispondenza per /extensions nella mappa degli URL. L'output è simile al seguente:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configura l'estensione della route.

    Console

    1. Nella console Google Cloud , vai alla pagina Estensioni di servizio.

      Vai a Service Extensions

    2. Fai clic su Crea estensione.

      Si apre una procedura guidata che ti guiderà attraverso alcuni passaggi iniziali.

    3. Per il prodotto, seleziona Bilanciamento del carico. Quindi, fai clic su Continua.

      Viene visualizzato un elenco di bilanciatori del carico delle applicazioni supportati.

    4. Per il tipo di bilanciatore del carico, seleziona il bilanciatore del carico delle applicazioni interno tra regioni. Quindi, fai clic su Continua.

    5. Come tipo di estensione, seleziona Estensioni di itinerario, quindi fai clic su Continua.

    6. Per aprire il modulo Crea estensione, fai clic su Continua.

      Nel modulo Crea estensione, nota che le selezioni precedenti, visualizzate nella parte superiore della pagina, non sono modificabili.

    7. Nella sezione Nozioni di base, segui questi passaggi:

      1. Specifica un nome univoco per l'estensione.

        Il nome deve iniziare con una lettera minuscola seguita da un massimo di 62 lettere minuscole, numeri o trattini e non deve terminare con un trattino.

      2. (Facoltativo) Inserisci una breve descrizione dell'estensione utilizzando un massimo di 1024 caratteri.

      3. (Facoltativo) Nella sezione Etichette, fai clic su Aggiungi etichetta. Quindi, nella riga visualizzata, procedi nel seguente modo:

        • In Chiave, inserisci un nome per la chiave.
        • In Valore, inserisci un valore per la chiave.

        Per aggiungere altre coppie chiave-valore, fai clic su Aggiungi etichetta. Puoi aggiungere un massimo di 64 coppie chiave-valore.

        Per saperne di più sulle etichette, consulta Creare e aggiornare le etichette per i progetti.

    8. Per Regole di forwarding, seleziona una o più regole di forwarding da associare all'estensione, ad esempio cr-ilb-forwarding-rule.

      Le regole di inoltro già associate a un'altra estensione non possono essere selezionate e vengono visualizzate come disattivate.

    9. Per le catene di estensioni, aggiungi una o più catene di estensioni da eseguire per una richiesta corrispondente.

      Per aggiungere una catena di estensioni, procedi nel seguente modo, quindi fai clic su Fine:

      • Per Nuova catena di estensioni, specifica un nome univoco.

        Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo carattere deve essere una lettera o un numero.

      • Per trovare le richieste per le quali viene eseguita la catena di estensioni, specifica un'espressione Common Expression Language (CEL) per Condizione di corrispondenza, ad esempio request.path.startsWith("/extensions").

        Per ulteriori informazioni sulle espressioni CEL, fai clic su Guida alla sintassi o consulta il riferimento al linguaggio del matcher CEL.

      • Aggiungi un'estensione da eseguire per una richiesta corrispondente. Per le estensioni di itinerario, puoi specificare una sola estensione.

        Nella sezione Estensioni, esegui le seguenti operazioni, quindi fai clic su Fine:

        • Per Tipo di programmabilità, seleziona Plug-in.

        • In Nome estensione, specifica un nome univoco.

          Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo una lettera o un numero.

        • In Plug-in, seleziona un plug-in creato utilizzando Service Extensions per lo stesso prodotto e tipo di estensione.

        • Per Inoltra intestazioni, fai clic su Aggiungi intestazione e poi aggiungi le intestazioni HTTP da inoltrare all'estensione (dal client o dal backend). Se non viene specificata un'intestazione, vengono inviate tutte le intestazioni.

        • (Facoltativo) Se l'estensione scade o non funziona e vuoi che l'elaborazione della richiesta o della risposta continui, per Fail open, seleziona Attivato.

          Per impostazione predefinita, l'opzione Fail open non è selezionata. In questo caso, quando si verifica un errore, l'elaborazione della richiesta o della risposta si interrompe. Se le intestazioni della risposta non sono state inviate al client downstream, al client viene restituito un codice di stato HTTP 500 generico. Se le intestazioni della risposta sono state recapitate, il flusso HTTP al client viene reimpostato.

          L'opzione predefinita di non selezionare Fail open è preferibile quando si dà la priorità alla sicurezza o all'integrità. L'attivazione di Fail open, in particolare per le operazioni non critiche, è utile quando si dà la priorità alla disponibilità.

    10. Fai clic su Crea estensione.

    gcloud

    1. Definisci il plug-in in un file YAML e associalo a una regola di forwarding globale, ad esempio cr-ilb-forwarding-rule.

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
EOF

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID progetto.
      • REGION: la regione della regola di forwarding. Il valore deve corrispondere a quello specificato per la posizione del plug-in.
      • LOCATION: la posizione del plug-in come global o una regione.
      • WASM_PLUGIN: l'ID o il nome completo del plug-in.

    2. Importa l'estensione route. Utilizza il comando gcloud service-extensions lb-route-extensions import con i seguenti valori di esempio.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route-plugin.yaml \
    --location=global

    Dopo la creazione di un'estensione del percorso, è necessario un po' di tempo prima che il nuovo plug-in venga distribuito in tutte le sedi. L'ora potrebbe variare a seconda della località perché il plug-in non viene distribuito in tutte le località contemporaneamente.

  3. Per verificare che l'estensione della route funzioni come previsto, utilizza lo stesso comando curl:

    curl FORWARDING_RULE_IP/extensions

    L'output è simile al seguente e indica che la pagina viene servita da una VM in region B:

    Page served from region-B-vm

    Per verificare che il plug-in venga eseguito solo per le richieste con il prefisso del percorso /extension, ripeti il comando curl senza un percorso.

    curl FORWARDING_RULE_IP

    L'output è simile al seguente:

    Page served from region-A-vm

Configurare utilizzando i callout

Questa sezione mostra come configurare un'estensione di itinerario utilizzando un callout.

Prima di iniziare

Crea le risorse richieste come descritto in Configura un servizio di backend callout.

Configurare un'estensione itinerario utilizzando un callout

L'esempio seguente mostra come configurare un'estensione di route da chiamare quando il percorso corrisponde a /extensions. Il server di callout della route in callout-vm modifica l'intestazione Host in service-extensions.com, imposta il percorso su / e poi invia un'istruzione al bilanciatore del carico per ricalcolare la route. Il traffico viene quindi indirizzato a l7-ilb-backend-service2 anziché a l7-ilb-backend-service.

  1. Controlla se esiste una corrispondenza per /extensions nella mappa URL.

    1. Esegui il seguente comando curl sulla regola di forwarding nella VM client:

      curl FORWARDING_RULE_IP/extensions

      Sostituisci FORWARDING_RULE_IP con l'indirizzo IP della regola di forwarding. Per trovare l'indirizzo IP, utilizza il comando gcloud compute forwarding-rules describe.

      L'output indica che non esiste alcuna corrispondenza per /extensions nella mappa degli URL. L'output è simile al seguente:

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. Configura l'estensione della route.

    Console

    1. Nella console Google Cloud , vai alla pagina Estensioni di servizio.

      Vai a Service Extensions

    2. Fai clic su Crea estensione.

      Si apre una procedura guidata che ti guiderà attraverso alcuni passaggi iniziali.

    3. Per il prodotto, seleziona Bilanciamento del carico. Quindi, fai clic su Continua.

      Viene visualizzato un elenco di bilanciatori del carico delle applicazioni supportati.

    4. Seleziona un tipo di bilanciatore del carico. Per i bilanciatori del carico a livello di regione, specifica anche la regione. Fai clic su Continua.

    5. Come tipo di estensione, seleziona Estensioni di itinerario, quindi fai clic su Continua.

    6. Per aprire il modulo Crea estensione, fai clic su Continua.

      Nel modulo Crea estensione, nota che le selezioni precedenti, visualizzate nella parte superiore della pagina, non sono modificabili.

    7. Nella sezione Nozioni di base, segui questi passaggi:

      1. Specifica un nome univoco per l'estensione.

        Il nome deve iniziare con una lettera minuscola seguita da un massimo di 62 lettere minuscole, numeri o trattini e non deve terminare con un trattino.

      2. (Facoltativo) Inserisci una breve descrizione dell'estensione utilizzando un massimo di 1024 caratteri.

      3. (Facoltativo) Nella sezione Etichette, fai clic su Aggiungi etichetta. Quindi, nella riga visualizzata, procedi nel seguente modo:

        • In Chiave, inserisci un nome per la chiave.
        • In Valore, inserisci un valore per la chiave.

        Per aggiungere altre coppie chiave-valore, fai clic su Aggiungi etichetta. Puoi aggiungere un massimo di 64 coppie chiave-valore.

        Per saperne di più sulle etichette, consulta Creare e aggiornare le etichette per i progetti.

    8. Per Regole di forwarding, seleziona una o più regole di forwarding da associare all'estensione, ad esempio l7-ilb-forwarding-rule.

      Le regole di inoltro già associate a un'altra estensione non possono essere selezionate e vengono visualizzate come disattivate.

    9. Per le catene di estensioni, aggiungi una o più catene di estensioni da eseguire per una richiesta corrispondente.

      Per aggiungere una catena di estensioni, procedi nel seguente modo, poi fai clic su Fine.

      • Per Nuova catena di estensioni, specifica un nome univoco.

        Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo carattere deve essere una lettera o un numero.

      • Per trovare le richieste per le quali viene eseguita la catena di estensioni, specifica un'espressione Common Expression Language (CEL) per Condizione di corrispondenza, ad esempio request.path.startsWith("/extensions").

        Per ulteriori informazioni sulle espressioni CEL, fai clic su Guida alla sintassi o consulta il riferimento al linguaggio del matcher CEL.

      • Aggiungi un'estensione da eseguire per una richiesta corrispondente. Per le estensioni di itinerario, puoi specificare una sola estensione.

        Nella sezione Estensioni, esegui le seguenti operazioni, quindi fai clic su Fine:

        • Per Tipo di programmabilità, seleziona Callout.

        • In Nome estensione, specifica un nome univoco.

          Il nome deve essere conforme a RFC-1034, utilizzare solo lettere minuscole, numeri e trattini e avere una lunghezza massima di 63 caratteri. Inoltre, il primo carattere deve essere una lettera e l'ultimo una lettera o un numero.

        • Per Authority, inserisci l'intestazione authority dalla richiesta gRPC inviata dal bilanciatore del carico al servizio di estensione.

        • Per Servizio di backend, seleziona un servizio di backend creato seguendo le istruzioni riportate in Configurare un servizio di backend callout.

        • Per Timeout, specifica un valore compreso tra 10 e 1000 millisecondi, dopo il quale un messaggio nel flusso va in timeout mentre il bilanciamento del carico è ancora in attesa di una risposta dal servizio ext_proc.

        • Per Inoltra intestazioni, fai clic su Aggiungi intestazione e poi aggiungi le intestazioni HTTP da inoltrare all'estensione (dal client o dal backend). Se non viene specificata un'intestazione, vengono inviate tutte le intestazioni.

        • (Facoltativo) Se l'estensione scade o non funziona e vuoi che l'elaborazione della richiesta o della risposta continui, per Fail open, seleziona Attivato. Vengono eseguite anche le estensioni successive nella catena.

          Per impostazione predefinita, l'opzione Fail open non è selezionata. In questo caso, quando si verifica un errore, l'elaborazione della richiesta o della risposta si interrompe. Se le intestazioni della risposta non sono state inviate al client downstream, al client viene restituito un codice di stato HTTP 500 generico. Se le intestazioni della risposta sono state recapitate, il flusso HTTP al client viene reimpostato.

          L'opzione predefinita di non selezionare Fail open è preferibile quando si dà la priorità alla sicurezza o all'integrità. L'attivazione di Fail open, in particolare per le operazioni non critiche, è utile quando si dà la priorità alla disponibilità.

        • In Metadati, fai clic su Aggiungi metadati e specifica i valori di esempio come suggerito. In Chiave, specifica key e in Valore, specifica value.

          Fai clic su Aggiungi metadati per aggiungere un'altra coppia chiave-valore. Per Chiave, specifica fr e per Valore, specifica forwarding_rule_id.

          Il campo Metadati consente di trasferire informazioni aggiuntive dal bilanciatore del carico al server delle estensioni. I metadati vengono inviati in un messaggio ProcessingRequest e codificati come protobuf.Struct. Qualsiasi testo all'interno dei metadati che corrisponde all'ID regola di forwarding specificato viene sostituito con l'URL della risorsa completo della regola di forwarding associata alla richiesta del client.

          La dimensione totale dei metadati deve essere inferiore a 1 KiB. Il numero totale di chiavi nei metadati deve essere inferiore a 16. La lunghezza di ogni chiave deve essere inferiore a 64 caratteri. La lunghezza di ogni valore deve essere inferiore a 1024 caratteri. Tutti i valori devono essere stringhe.

    10. Fai clic su Crea estensione.

    gcloud

    1. Definisci il callout in un file YAML e associalo alla regola di forwarding. Utilizza i valori di esempio forniti.

      cat >route.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
EOF

      Sostituisci PROJECT_ID con l'ID progetto.

      Il campo metadata nella configurazione dell'estensione consente di trasferire informazioni aggiuntive dal bilanciatore del carico al server di estensione. I metadati vengono inviati in un messaggio ProcessingRequest e codificati come protobuf.Struct. Qualsiasi testo all'interno dei metadati che corrisponde all'ID regola di forwarding specificato viene sostituito con l'URL risorsa completo della regola di forwarding associata alla richiesta del client.

      La dimensione totale di metadata deve essere inferiore a 1 KiB. Il numero totale di chiavi nei metadati deve essere inferiore a 16. La lunghezza di ogni chiave deve essere inferiore a 64 caratteri. La lunghezza di ogni valore deve essere inferiore a 1024 caratteri. Tutti i valori devono essere stringhe.

    2. Importa l'estensione route. Utilizza il comando gcloud service-extensions lb-route-extensions import con i seguenti valori di esempio.

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route.yaml \
    --location=us-west1

  3. Verifica che l'estensione del percorso funzioni come previsto. Utilizza lo stesso comando curl:

    curl FORWARDING_RULE_IP/extensions

    L'output indica che il traffico corrisponde all'host virtuale service-extensions.com e ha raggiunto il servizio l7-ilb-backend-service2 anche se la richiesta originale non lo ha fatto. L'output è simile al seguente:

    Page served from second backend service

    Per verificare che il callout abbia come target solo le richieste con il prefisso /extension, ripeti il comando curl senza il prefisso path.

    curl FORWARDING_RULE_IP

    L'output è simile al seguente:

    Page served from: l7-ilb-backend-example-1c7t

Limitazioni per le estensioni di itinerario

  • Le estensioni di route non supportano l'elaborazione del corpo HTTP.
  • Una risposta diretta dall'estensione al client non è supportata per le estensioni di percorso. Se il server di estensione dell'itinerario risponde a una richiesta di elaborazione con una risposta di elaborazione che contiene una risposta diretta, il bilanciatore del carico ignora la risposta di elaborazione.

Per le limitazioni applicabili a tutte le estensioni, consulta Limitazioni per le estensioni.

Passaggi successivi