YARP-utökningsbarhet: Konfigurationsprovidrar

Introduktion

Basic Yarp-exempel visar proxykonfiguration som laddas från appsettings.json. I stället kan proxykonfiguration läsas in programmatiskt från valfri källa. Det gör du genom att tillhandahålla ett par klasser som implementerar IProxyConfigProvider och IProxyConfig.

Se ReverseProxy.Code.Sample för ett exempel på en anpassad konfigurationsprovider.

Konfigurationen kan ändras under belastningssekvensen med Konfigurationsfilter.

Struktur

IProxyConfigProvider har en enda metod GetConfig() som ska returnera en IProxyConfig-instans. IProxyConfig innehåller listor över aktuella vägar och kluster, samt en IChangeToken för att meddela proxyn när den här informationen är inaktuell och bör läsas in igen, vilket gör att GetConfig() anropas igen.

Vägar

Avsnittet vägar är en osorterad samling med namngivna vägar. En rutt innehåller matchningar och deras associerade inställningar. En väg kräver minst följande fält:

• RouteId – ett unikt namn
• ClusterId – refererar till namnet på en post i avsnittet kluster.
• Match – innehåller antingen en hosts-matris eller en sökvägsmönstersträng. Path är en ASP.NET Core-vägmall som kan definieras på det sätt som beskrivs här.

Rubriker, Authorization, CORSoch andra ruttbaserade principer kan konfigureras för varje rutteinträde. Ytterligare fält finns i RouteConfig.

Proxyn tillämpar de angivna matchande kriterierna och principerna och skickar sedan begäran till det angivna klustret.

Kluster

Avsnittet kluster är en osorterad samling med namngivna kluster. Ett kluster innehåller främst en samling namngivna mål och deras adresser, som alla anses kunna hantera begäranden för en viss väg. Proxyn bearbetar begäran enligt routnings- och klusterkonfigurationen för att välja ett mål.

Ytterligare fält finns i ClusterConfig.

Minneskonfiguration

InMemoryConfigProvider implementerar IProxyConfigProvider och gör det möjligt att ange vägar och kluster direkt i kod genom att anropa LoadFromMemory.

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

Om du vill uppdatera konfigurationen senare löser du InMemoryConfigProvider från tjänstcontainern och anropar Update med de nya listorna över vägar och kluster.

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

Livscykel

Startup-företag

IProxyConfigProvider bör registreras i DI-containern som en singleton. Vid start löser proxyn den här instansen och anropar GetConfig(). Vid det första anropet kan leverantören välja att:

• Utlöser ett undantag om providern inte kan skapa en giltig proxykonfiguration av någon anledning. Detta förhindrar att programmet startas.
• Blockera synkront när konfigurationen läses in. Detta blockerar programmet från att starta tills giltiga routningsdata är tillgängliga.
• Eller så kan den välja att returnera en tom IProxyConfig instans medan den läser in konfigurationen i bakgrunden. Providern måste utlösa IChangeToken när konfigurationen är tillgänglig.

Proxyn verifierar den angivna konfigurationen och om den är ogiltig utlöses ett undantag som hindrar programmet från att starta. Providern kan undvika detta genom att använda IConfigValidator för att förverifiera vägar och kluster och vidta de åtgärder som den anser lämpliga, till exempel att utesluta ogiltiga poster.

Atomicitet

Konfigurationsobjekten och samlingarna som skickas till proxyn ska vara skrivskyddade och inte ändras när de har överlämnats till proxyn via GetConfig().

Ladda om

Om IChangeToken stöder ActiveChangeCallbacksregistreras ett återanrop med den här token när proxyn har bearbetat den första konfigurationsuppsättningen. Om providern inte stöder återanrop avsöks HasChanged var femte minut.

När providern vill tillhandahålla en ny konfiguration till proxyn bör den:

• Läs in konfigurationen i bakgrunden.
  • Routnings- och klusterobjekt är oföränderliga, så nya instanser måste skapas för alla nya data.
  • Objekt för oförändrade vägar och kluster kan återanvändas, eller så kan nya instanser skapas – ändringar identifieras genom att de diffas.
• Du kan också verifiera konfigurationen med IConfigValidator och först sedan signalera IChangeToken från den tidigare IProxyConfig instansen att nya data är tillgängliga. Proxyn anropar GetConfig() igen för att hämta nya data.

Det finns viktiga skillnader vid återinläsning av konfiguration jämfört med första gången konfigurationen läses in.

• Den nya konfigurationen kommer att jämföras med den aktuella och endast ändrade rutter eller kluster kommer att uppdateras. Uppdateringen kommer att tillämpas atomiskt och påverkar bara nya begäranden, inte begäranden som för närvarande pågår.
• Eventuella fel i omläsningsprocessen loggas och ignoreras. Programmet fortsätter att använda den senast kända bra konfigurationen.
• Om GetConfig() kastar ett fel kan proxyn inte lyssna efter framtida ändringar eftersom IChangeTokens är för engångsbruk.

När den nya konfigurationen har verifierats och tillämpats registrerar proxyn ett återanrop med den nya IChangeToken. Observera att om det finns flera omladdningar som signaleras i nära följd kan proxyn hoppa över vissa och läsa in nästa tillgängliga konfiguration så snart den är klar. Varje IProxyConfig innehåller det fullständiga konfigurationstillståndet så att ingenting går förlorat.

Flera konfigurationskällor

Från och med 1.1 stöder YARP inläsning av proxykonfigurationen från flera källor. Flera IProxyConfigProviderkan registreras som singleton-tjänster och alla kommer att lösas och kombineras. Källorna kan vara samma eller olika typer, till exempel IConfiguration eller InMemory. Vägar kan referera till kluster från andra källor. Observera att sammanslagning av partiell konfiguration från olika källor för en viss väg eller ett visst kluster inte stöds.

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

eller

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

Exempel

InMemoryConfigProvider ger ett exempel på en IProxyConfigProvider som har rutter och kluster som har laddats in manuellt.