Udostępnij za pośrednictwem

Pliki konfiguracji YARP

Wprowadzenie

Zwrotny serwer proxy może załadować konfigurację tras i klastrów z plików przy użyciu abstrakcji IConfiguration z Microsoft.Extensions. Przykłady podane w tym miejscu używają kodu JSON, ale każde źródło IConfiguration powinno działać. Konfiguracja zostanie również zaktualizowana bez ponownego uruchomienia serwera proxy, jeśli plik źródłowy ulegnie zmianie.

Ładowanie konfiguracji

Aby załadować konfigurację serwera proxy z poziomu konfiguracji IConfiguration, dodaj następujący kod w Program.cs:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

// Add the reverse proxy capability to the server
builder.Services.AddReverseProxy()
    // Initialize the reverse proxy from the "ReverseProxy" section of configuration
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));

var app = builder.Build();

// Register the reverse proxy routes
app.MapReverseProxy();

app.Run();

Uwaga: Aby uzyskać szczegółowe informacje na temat zamawiania oprogramowania pośredniczącego, zobacz tutaj.

Konfigurację można zmodyfikować podczas sekwencji ładowania przy użyciu filtrów konfiguracji .

Wiele źródeł konfiguracji

Od wersji 1.1 usługa YARP obsługuje ładowanie konfiguracji serwera proxy z wielu źródeł. LoadFromConfig może być wywoływana wiele razy odwołując się do różnych sekcji IConfiguration lub może być łączna z innym źródłem konfiguracji, na przykład InMemory. Trasy mogą odwoływać się do klastrów z innych źródeł. Zwróć uwagę, że scalanie częściowej konfiguracji z różnych źródeł dla danej trasy lub klastra nie jest obsługiwane.

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

lub


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

Kontrakt konfiguracji

Konfiguracja oparta na plikach jest dynamicznie mapowana na typy w przestrzeni nazw Yarp.ReverseProxy.Configuration przez implementację IProxyConfigProvider, która jest uruchamiana na starcie aplikacji i przy każdej zmianie konfiguracji.

Struktura konfiguracji

Konfiguracja składa się z nazwanej sekcji, którą określiłeś powyżej poprzez Configuration.GetSection("ReverseProxy"), i zawiera podsekcje dla tras i grup.

Przykład:

{
  "ReverseProxy": {
    "Routes": {
      "route1" : {
        "ClusterId": "cluster1",
        "Match": {
          "Path": "{**catch-all}",
          "Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"]
        }
      }
    },
    "Clusters": {
      "cluster1": {
        "Destinations": {
          "cluster1/destination1": {
            "Address": "https://example.com/"
          }
        }
      }
    }
  }
}

Trasy

Sekcja tras to nieuporządkowany zbiór dopasowań tras i ich powiązanej konfiguracji. Trasa wymaga co najmniej następujących pól:

  • RouteId — unikatowa nazwa
  • ClusterId — odnosi się do nazwy wpisu w sekcji klastrów.
  • Dopasowanie – zawiera albo tablicę hostów, albo ciąg wzorca ścieżki. Ścieżka to szablon trasy ASP.NET Core, który można zdefiniować jako wyjaśniony tutaj.

Dopasowywanie tras jest oparte na najbardziej określonych trasach o najwyższym priorytecie, jak opisano tutaj. Jawne porządkowanie można osiągnąć przy użyciu pola order, a niższe wartości mają wyższy priorytet.

Nagłówki, Autoryzacja, CORSi inne zasady oparte na trasach można skonfigurować dla każdego wpisu trasy. Aby uzyskać więcej pól, zobacz RouteConfig.

Serwer proxy zastosuje podane kryteria dopasowania i zasady, a następnie przekaże żądanie do określonego klastra.

Klastry

Sekcja klastrów jest nieuporządkowaną kolekcją nazwanych klastrów. Klaster zawiera przede wszystkim kolekcję nazwanych miejsc docelowych i ich adresów, z których każdy jest uważany za zdolny do obsługi żądań dla danej trasy. Serwer proxy przetworzy żądanie zgodnie z konfiguracją trasy i klastra w celu wybrania miejsca docelowego.

Aby uzyskać więcej pól, zobacz ClusterConfig.

Wszystkie właściwości konfiguracji

{
  // Base URLs the server listens on, must be configured independently of the routes below
  "Urls": "http://localhost:5000;https://localhost:5001",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      // Uncomment to hide diagnostic messages from runtime and proxy
      // "Microsoft": "Warning",
      // "Yarp" : "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "ReverseProxy": {
    // Routes tell the proxy which requests to forward
    "Routes": {
      "minimumroute" : {
        // Matches anything and routes it to www.example.com
        "ClusterId": "minimumcluster",
        "Match": {
          "Path": "{**catch-all}"
        }
      },
      "allrouteprops" : {
        // matches /something/* and routes to "allclusterprops"
        "ClusterId": "allclusterprops", // Name of one of the clusters
        "Order" : 100, // Lower numbers have higher precedence
        "MaxRequestBodySize" : 1000000, // In bytes. An optional override of the server's limit (30MB default). Set to -1 to disable.
        "AuthorizationPolicy" : "Anonymous", // Name of the policy or "Default", "Anonymous"
        "CorsPolicy" : "Default", // Name of the CorsPolicy to apply to this route or "Default", "Disable"
        "Match": {
          "Path": "/something/{**remainder}", // The path to match using ASP.NET syntax.
          "Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"], // The host names to match, unspecified is any
          "Methods" : [ "GET", "PUT" ], // The HTTP methods that match, uspecified is all
          "Headers": [ // The headers to match, unspecified is any
            {
              "Name": "MyCustomHeader", // Name of the header
              "Values": [ "value1", "value2", "another value" ], // Matches are against any of these values
              "Mode": "ExactHeader", // or "HeaderPrefix", "Exists" , "Contains", "NotContains", "NotExists"
              "IsCaseSensitive": true
            }
          ],
          "QueryParameters": [ // The query parameters to match, unspecified is any
            {
              "Name": "MyQueryParameter", // Name of the query parameter
              "Values": [ "value1", "value2", "another value" ], // Matches are against any of these values
              "Mode": "Exact", // or "Prefix", "Exists" , "Contains", "NotContains"
              "IsCaseSensitive": true
            }
          ]
        },
        "Metadata" : { // List of key value pairs that can be used by custom extensions
          "MyName" : "MyValue"
        },
        "Transforms" : [ // List of transforms. See the Transforms article for more details
          {
            "RequestHeader": "MyHeader",
            "Set": "MyValue"
          }
        ]
      }
    },
    // Clusters tell the proxy where and how to forward requests
    "Clusters": {
      "minimumcluster": {
        "Destinations": {
          "example.com": {
            "Address": "http://www.example.com/"
          }
        }
      },
      "allclusterprops": {
        "Destinations": {
          "first_destination": {
            "Address": "https://contoso.com"
          },
          "another_destination": {
            "Address": "https://10.20.30.40",
            "Health" : "https://10.20.30.40:12345/test" // override for active health checks
          }
        },
        "LoadBalancingPolicy" : "PowerOfTwoChoices", // Alternatively "FirstAlphabetical", "Random", "RoundRobin", "LeastRequests"
        "SessionAffinity": {
          "Enabled": true, // Defaults to 'false'
          "Policy": "Cookie", // Default, alternatively "CustomHeader"
          "FailurePolicy": "Redistribute", // default, Alternatively "Return503Error"
          "Settings" : {
              "CustomHeaderName": "MySessionHeaderName" // Defaults to 'X-Yarp-Proxy-Affinity`
          }
        },
        "HealthCheck": {
          "Active": { // Makes API calls to validate the health.
            "Enabled": "true",
            "Interval": "00:00:10",
            "Timeout": "00:00:10",
            "Policy": "ConsecutiveFailures",
            "Path": "/api/health", // API endpoint to query for health state
            "Query": "?foo=bar"
          },
          "Passive": { // Disables destinations based on HTTP response codes
            "Enabled": true, // Defaults to false
            "Policy" : "TransportFailureRateHealthPolicy", // Required
            "ReactivationPeriod" : "00:00:10" // 10s
          }
        },
        "HttpClient" : { // Configuration of HttpClient instance used to contact destinations
          "SSLProtocols" : "Tls13",
          "DangerousAcceptAnyServerCertificate" : false,
          "MaxConnectionsPerServer" : 1024,
          "EnableMultipleHttp2Connections" : true,
          "RequestHeaderEncoding" : "Latin1", // How to interpret non ASCII characters in request header values
          "ResponseHeaderEncoding" : "Latin1" // How to interpret non ASCII characters in response header values
        },
        "HttpRequest" : { // Options for sending request to destination
          "ActivityTimeout" : "00:02:00",
          "Version" : "2",
          "VersionPolicy" : "RequestVersionOrLower",
          "AllowResponseBuffering" : "false"
        },
        "Metadata" : { // Custom Key value pairs
          "TransportFailureRateHealthPolicy.RateLimit": "0.5", // Used by Passive health policy
          "MyKey" : "MyValue"
        }
      }
    }
  }
}

Aby uzyskać więcej informacji, zobacz konfiguracja rejestrowania i konfiguracja klienta HTTP.