Fichiers de configuration YARP

2025-04-17

Présentation

Le proxy inverse peut charger la configuration des itinéraires et des clusters à partir de fichiers à l’aide de l’abstraction IConfiguration de Microsoft.Extensions. Les exemples fournis ici utilisent JSON, mais toute source IConfiguration doit fonctionner. La configuration est également mise à jour sans redémarrer le proxy si le fichier source change.

Chargement de la configuration

Pour charger la configuration du proxy à partir de IConfiguration, ajoutez le code suivant dans 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();

Remarque: pour plus d’informations sur l’ordre des intergiciels, consultez ici.

La configuration peut être modifiée pendant la séquence de chargement à l’aide des filtres de configuration.

Sources de configuration multiples

À compter de la version 1.1, YARP prend en charge le chargement de la configuration du proxy à partir de plusieurs sources. LoadFromConfig peut être appelé plusieurs fois référençant différentes sections IConfiguration ou peut être combiné avec une autre source de configuration comme InMemory. Les itinéraires peuvent référencer des clusters à partir d’autres sources. Notez que la fusion d’une configuration partielle à partir de différentes sources pour un itinéraire ou un cluster donné n’est pas prise en charge.

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


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

Contrat de configuration

La configuration basée sur les fichiers est mappée dynamiquement aux types dans l'espace de noms Yarp.ReverseProxy.Configuration par une implémentation de IProxyConfigProvider, laquelle convertit cette configuration au démarrage de l’application et chaque fois que la configuration change.

Structure de configuration

La configuration se compose d’une section nommée que vous avez spécifiée ci-dessus via Configuration.GetSection("ReverseProxy")et contient des sous-sections pour les itinéraires et les clusters.

Exemple:

{
  "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/"
          }
        }
      }
    }
  }
}

Itinéraires

La section routes est une collection non ordonnée de correspondances de routes avec leur configuration associée. Un itinéraire nécessite au moins les champs suivants :

RouteId - un nom unique
ClusterId : fait référence au nom d’une entrée dans la section clusters.
Correspondance : contient soit un tableau Hosts, soit une chaîne de motif Path. Path est un modèle d’itinéraire ASP.NET Core qui peut être défini comme décrit ici.

La correspondance des itinéraires est basée sur les itinéraires les plus spécifiques ayant la priorité la plus élevée, comme décrit ici. Vous pouvez obtenir un ordre explicite à l’aide du champ order, avec des valeurs inférieures prenant une priorité plus élevée.

Les stratégies basées sur les itinéraires, comme Headers, Authorization et CORS, peuvent être configurées sur chaque entrée d’itinéraire. Pour obtenir des champs supplémentaires, consultez RouteConfig.

Le proxy applique les critères et stratégies correspondants donnés, puis transmet la requête au cluster spécifié.

Clusters

La section groupes est une collection non ordonnée de groupes nommés. Un cluster contient principalement une collection de destinations nommées et de leurs adresses, dont l’une est considérée comme capable de gérer les demandes d’un itinéraire donné. Le proxy traite la requête en fonction de la configuration de l’itinéraire et du cluster pour sélectionner une destination.

Pour des champs supplémentaires, consultez ClusterConfig.

Toutes les propriétés de configuration

{
  // 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"
        }
      }
    }
  }
}

Pour plus d’informations, consultez configuration de journalisation et configuration du client HTTP.