Estendibilità YARP: provider di configurazione

Introduzione

L'esempio di base Yarp mostra che la configurazione proxy viene caricata da appsettings.json. Al contrario, la configurazione proxy può essere caricata tramite codice dall'origine scelta. Per fare ciò, fornisci un paio di classi che implementano IProxyConfigProvider e IProxyConfig.

Per un esempio di provider di configurazione personalizzato, vedere ReverseProxy.Code.Sample.

La configurazione può essere modificata durante la sequenza di caricamento usando i filtri di configurazione .

Struttura

IProxyConfigProvider include un singolo metodo GetConfig() che deve restituire un'istanza di IProxyConfig. IProxyConfig include elenchi delle route e dei cluster correnti, nonché un IChangeToken per notificare al proxy quando queste informazioni non sono aggiornate e devono essere ricaricate, il che causerà la chiamata di nuovo GetConfig().

Percorsi

La sezione dei percorsi è una raccolta non ordinata di percorsi denominati. Un percorso contiene corrispondenze e la configurazione associata. Una route richiede almeno i campi seguenti:

• RouteId : nome univoco
• ClusterId: fa riferimento al nome di una voce nella sezione cluster.
• Match - contiene un array di host o una stringa di percorso. Path è un modello di route core ASP.NET che può essere definito come illustrato qui.

Intestazioni, Autorizzazione, CORSe altri criteri basati su route possono essere configurati in ogni voce di route. Per altri campi, vedere RouteConfig.

Il proxy applicherà i criteri di corrispondenza e le politiche fornite, e quindi inoltrerà la richiesta al cluster specificato.

Cluster

La sezione dei raggruppamenti è una collezione senza un ordine di raggruppamenti denominati. Un cluster contiene principalmente una raccolta di destinazioni denominate e i relativi indirizzi, uno dei quali è considerato in grado di gestire le richieste per una determinata route. Il proxy elabora la richiesta in base alla route e alla configurazione del cluster per selezionare una destinazione.

Per altri campi, vedere ClusterConfig.

Nella configurazione della memoria

Il InMemoryConfigProvider implementa IProxyConfigProvider e consente di specificare route e cluster direttamente nel codice chiamando LoadFromMemory.

services.AddReverseProxy().LoadFromMemory(routes, clusters);

Per aggiornare la configurazione in un secondo momento, risolvere il InMemoryConfigProvider dal contenitore dei servizi e chiamare Update con i nuovi elenchi di route e cluster.

httpContext.RequestServices.GetRequiredService<InMemoryConfigProvider>().Update(routes, clusters);

Ciclo di vita

Startup

Il IProxyConfigProvider deve essere registrato nel contenitore DI come singleton. All'avvio, il proxy risolverà questa istanza e chiamerà GetConfig(). In questa prima chiamata il provider può scegliere di:

• Generare un'eccezione se il provider non può produrre una configurazione proxy valida per qualsiasi motivo. Ciò impedirà l'avvio dell'applicazione.
• Blocca in modo sincrono mentre carica la configurazione. In questo modo l'applicazione verrà bloccata fino a quando non saranno disponibili dati di route validi.
• In alternativa, può scegliere di restituire un'istanza di IProxyConfig vuota mentre carica la configurazione in background. Il provider dovrà attivare il IChangeToken quando la configurazione è disponibile.

Il proxy convaliderà la configurazione specificata e, se non è valida, verrà generata un'eccezione che impedisce l'avvio dell'applicazione. Il provider può evitare questo problema usando il IConfigValidator per pre-convalidare percorsi e cluster e intraprendere qualsiasi azione ritenuta opportuna, come escludere voci non valide.

Atomicità

Gli oggetti di configurazione e le raccolte forniti al proxy devono essere di sola lettura e non devono essere modificati dopo che sono stati passati al proxy tramite GetConfig().

Ricaricare

Se il IChangeToken supporta ActiveChangeCallbacks, una volta elaborato il set iniziale di configurazioni, il proxy registrerà un callback con questo token. HasChanged verrà interrogato ogni 5 minuti se il provider non supporta i callback.

Quando il provider vuole fornire una nuova configurazione al proxy, deve:

• Carica la configurazione in background.
  • Gli oggetti route e cluster non sono modificabili, pertanto è necessario creare nuove istanze per i nuovi dati.
  • Gli oggetti per le route e i cluster non modificati possono essere riutilizzati oppure è possibile creare nuove istanze - le modifiche verranno rilevate confrontandoli.
• Facoltativamente, convalidare la configurazione usando IConfigValidator, e solo allora segnalare all'istanza IChangeToken precedente IProxyConfig che sono disponibili nuovi dati. Il proxy chiamerà di nuovo GetConfig() per recuperare i nuovi dati.

Esistono differenze importanti durante il ricaricamento della configurazione rispetto al primo carico di configurazione.

• La nuova configurazione sarà confrontata con quella corrente e verranno aggiornate solo le rotte o i cluster modificati. L'aggiornamento verrà applicato in modo atomico e influirà solo sulle nuove richieste, non sulle richieste attualmente in corso.
• Eventuali errori nel processo di ricaricamento verranno registrati e eliminati. L'applicazione continuerà a usare l'ultima configurazione valida nota.
• Se GetConfig() lancia, il proxy non sarà in grado di restare in ascolto delle modifiche future perché i IChangeTokensono monouso.

Dopo aver convalidato e applicato la nuova configurazione, il proxy registrerà un callback con il nuovo IChangeToken. Si noti che se sono presenti più ricaricamenti segnalati in successione ravvicinata, il proxy potrebbe ignorare alcuni e caricare la configurazione successiva disponibile non appena è pronta. Ogni IProxyConfig contiene lo stato di configurazione completo, quindi non verrà perso nulla.

Molteplici origini di configurazione

A partire dalla versione 1.1, YARP supporta il caricamento della configurazione del proxy da più origini. È possibile registrare più IProxyConfigProvider come servizi singleton e tutti verranno risolti e combinati. Le origini possono essere uguali o diversi tipi, ad esempio IConfiguration o InMemory. I percorsi possono fare riferimento a cluster da altre origini. Si noti che l'unione di una configurazione parziale da origini diverse per una route o un cluster specificato non è supportata.

    services.AddReverseProxy()
        .LoadFromConfig(Configuration.GetSection("ReverseProxy1"))
        .LoadFromConfig(Configuration.GetSection("ReverseProxy2"));

o

    services.AddReverseProxy()
        .LoadFromMemory(routes, clusters)
        .LoadFromConfig(Configuration.GetSection("ReverseProxy"));

Esempio

Il InMemoryConfigProvider fornisce un esempio di IProxyConfigProvider con route e cluster caricati manualmente in esso.