Skip to content

Commit 3853fc5

Browse files
Rick-AndersonRick-Anderson
committed
yarp migration /2
1 parent cd02708 commit 3853fc5

35 files changed

+5214
-0
lines changed

‎aspnetcore/fundamentals/servers/yarp/ab-testing.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# A/B Testing and Rolling Upgrades
2+
3+
## Introduction
4+
5+
A/B testing and rolling upgrades require procedures for dynamically assigning incoming traffic to evaluate changes in the destination application. YARP does not have a built-in model for this, but it does expose some infrastructure useful for building such a system. See [issue #126](https://github.com/microsoft/reverse-proxy/issues/126) for additional details about this scenario.
6+
7+
## Example
8+
9+
```
10+
app.MapReverseProxy(proxyPipeline =>
11+
{
12+
// Custom cluster selection
13+
proxyPipeline.Use((context, next) =>
14+
{
15+
var lookup = context.RequestServices.GetRequiredService<IProxyStateLookup>();
16+
if (lookup.TryGetCluster(ChooseCluster(context), out var cluster))
17+
{
18+
context.ReassignProxyRequest(cluster);
19+
}
20+
21+
return next();
22+
});
23+
proxyPipeline.UseSessionAffinity();
24+
proxyPipeline.UseLoadBalancing();
25+
});
26+
27+
string ChooseCluster(HttpContext context)
28+
{
29+
// Decide which cluster to use. This could be random, weighted, based on headers, etc.
30+
return Random.Shared.Next(2) == 1 ? "cluster1" : "cluster2";
31+
}
32+
```
33+
34+
## Usage
35+
36+
This scenario makes use of two APIs, [IProxyStateLookup](xref:Yarp.ReverseProxy.IProxyStateLookup) and [ReassignProxyRequest](xref:Microsoft.AspNetCore.Http.HttpContextFeaturesExtensions.ReassignProxyRequest(Microsoft.AspNetCore.Http.HttpContext,Yarp.ReverseProxy.Model.ClusterState)), called from a custom proxy middleware as shown in the sample above.
37+
38+
`IProxyStateLookup` is a service available in the Dependency Injection container that can be used to look up or enumerate the current routes and clusters. Note this data may change if the configuration changes. An A/B orchestration algorithm can examine the request, decide which cluster to send it to, and then retrieve that cluster from `IProxyStateLookup.TryGetCluster`.
39+
40+
Once the cluster is selected, `ReassignProxyRequest` can be called to assign the request to that cluster. This updates the [IReverseProxyFeature](xref:Yarp.ReverseProxy.Model.IReverseProxyFeature) with the new cluster and destination information needed for the rest of the proxy middleware pipeline to handle the request.
41+
42+
## Session affinity
43+
44+
Note that session affinity functionality is split between middleware, which reads it settings from the current cluster, and transforms, which are part of the original route. Clusters used for A/B testing should use the same session affinity configuration to avoid conflicts.
45+

‎aspnetcore/fundamentals/servers/yarp/authn-authz.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Authentication and Authorization
2+
3+
## Introduction
4+
The reverse proxy can be used to authenticate and authorize requests before they are proxied to the destination servers. This can reduce load on the destination servers, add a layer of protection, and ensure consistent policies are implemented across your applications.
5+
6+
## Defaults
7+
8+
No authentication or authorization is performed on requests unless enabled in the route or application configuration.
9+
10+
## Configuration
11+
Authorization policies can be specified per route via [RouteConfig.AuthorizationPolicy](xref:Yarp.ReverseProxy.Configuration.RouteConfig) and can be bound from the `Routes` sections of the config file. As with other route properties, this can be modified and reloaded without restarting the proxy. Policy names are case insensitive.
12+
13+
Example:
14+
```JSON
15+
{
16+
"ReverseProxy": {
17+
"Routes": {
18+
"route1" : {
19+
"ClusterId": "cluster1",
20+
"AuthorizationPolicy": "customPolicy",
21+
"Match": {
22+
"Hosts": [ "localhost" ]
23+
}
24+
}
25+
},
26+
"Clusters": {
27+
"cluster1": {
28+
"Destinations": {
29+
"cluster1/destination1": {
30+
"Address": "https://localhost:10001/"
31+
}
32+
}
33+
}
34+
}
35+
}
36+
}
37+
```
38+
39+
[Authorization policies](https://docs.microsoft.com/aspnet/core/security/authorization/policies) are an ASP.NET Core concept that the proxy utilizes. The proxy provides the above configuration to specify a policy per route and the rest is handled by existing ASP.NET Core authentication and authorization components.
40+
41+
Authorization policies can be configured in the application as follows:
42+
```
43+
services.AddAuthorization(options =>
44+
{
45+
options.AddPolicy("customPolicy", policy =>
46+
policy.RequireAuthenticatedUser());
47+
});
48+
```
49+
50+
In Program.cs add the Authorization and Authentication middleware.
51+
52+
```
53+
app.UseAuthentication();
54+
app.UseAuthorization();
55+
56+
app.MapReverseProxy();
57+
```
58+
59+
See the [Authentication](https://docs.microsoft.com/aspnet/core/security/authentication/) docs for setting up your preferred kind of authentication.
60+
61+
### Special values:
62+
63+
In addition to custom policy names, there are two special values that can be specified in a route's authorization parameter: `default` and `anonymous`. ASP.NET Core also has a FallbackPolicy setting that applies to routes that do not specify a policy.
64+
65+
#### DefaultPolicy
66+
67+
Specifying the value `default` in a route's authorization parameter means that route will use the policy defined in [AuthorizationOptions.DefaultPolicy](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.authorization.authorizationoptions.defaultpolicy?#Microsoft_AspNetCore_Authorization_AuthorizationOptions_DefaultPolicy). That policy is pre-configured to require authenticated users.
68+
69+
#### Anonymous
70+
71+
Specifying the value `anonymous` in a route's authorization parameter means that route will not require authorization regardless of any other configuration in the application such as the FallbackPolicy.
72+
73+
#### FallbackPolicy
74+
75+
[AuthorizationOptions.FallbackPolicy](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.authorization.authorizationoptions.fallbackpolicy) is the policy that will be used for any request or route that was not configured with a policy. FallbackPolicy does not have a value by default, any request will be allowed.
76+
77+
## Flowing Credentials
78+
79+
Even after a request has been authorized in the proxy, the destination server may still need to know who the user is (authentication) and what they're allowed to do (authorization). How you flow that information will depend on the type of authentication being used.
80+
81+
### Cookie, bearer, API keys
82+
83+
These authentication types already pass their values in the request headers and these will flow to the destination server by default. That server will still need to verify and interpret those values, causing some double work.
84+
85+
### OAuth2, OpenIdConnect, WsFederation
86+
87+
These protocols are commonly used with remote identity providers. The authentication process can be configured in the proxy application and will result in an authentication cookie. That cookie will flow to the destination server as a normal request header.
88+
89+
### Windows, Negotiate, NTLM, Kerberos
90+
91+
These authentication types are often bound to a specific connection. They are not supported as means of authenticating a user in a destination server behind the YARP proxy (see [#166](https://github.com/microsoft/reverse-proxy/issues/166). They can be used to authenticate an incoming request to the proxy, but that identity information will have to be communicated to the destination server in another form. They can also be used to authenticate the proxy to the destination servers, but only as the proxy's own user, impersonating the client is not supported.
92+
93+
### Client Certificates
94+
95+
Client certificates are a TLS feature and are negotiated as part of a connection. See [these docs](https://docs.microsoft.com/aspnet/core/security/authentication/certauth) for additional information. The certificate can be forwarded to the destination server as an HTTP header using the [ClientCert](transforms.md#clientcert) transform.
96+
97+
### Swapping authentication types
98+
99+
Authentication types like Windows that don't flow naturally to the destination server will need to be converted in the proxy to an alternate form. For example a JWT bearer token can be created with the user information and set on the proxy request.
100+
101+
These swaps can be performed using [custom request transforms](transforms.md#from-code). Detailed examples can be developed for specific scenarios if there is enough community interest. We need more community feedback on how you want to convert and flow identity information.

‎aspnetcore/fundamentals/servers/yarp/config-files.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Configuration Files
2+
3+
## Introduction
4+
The reverse proxy can load configuration for routes and clusters from files using the IConfiguration abstraction from Microsoft.Extensions. The examples given here use JSON, but any IConfiguration source should work. The configuration will also be updated without restarting the proxy if the source file changes.
5+
6+
## Loading Configuration
7+
To load the proxy configuration from IConfiguration add the following code in Program.cs:
8+
```c#
9+
using Microsoft.AspNetCore.Builder;
10+
using Microsoft.Extensions.DependencyInjection;
11+
12+
var builder = WebApplication.CreateBuilder(args);
13+
14+
// Add the reverse proxy capability to the server
15+
builder.Services.AddReverseProxy()
16+
// Initialize the reverse proxy from the "ReverseProxy" section of configuration
17+
.LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));
18+
19+
var app = builder.Build();
20+
21+
// Register the reverse proxy routes
22+
app.MapReverseProxy();
23+
24+
app.Run();
25+
```
26+
**Note**: For details about middleware ordering see [here](https://docs.microsoft.com/aspnet/core/fundamentals/middleware/#middleware-order).
27+
28+
Configuration can be modified during the load sequence using [Configuration Filters](config-filters.md).
29+
30+
## Multiple Configuration Sources
31+
As of 1.1, YARP supports loading the proxy configuration from multiple sources. LoadFromConfig may be called multiple times referencing different IConfiguration sections or may be combine with a different config source like InMemory. Routes can reference clusters from other sources. Note merging partial config from different sources for a given route or cluster is not supported.
32+
33+
```c#
34+
services.AddReverseProxy()
35+
.LoadFromConfig(Configuration.GetSection("ReverseProxy1"))
36+
.LoadFromConfig(Configuration.GetSection("ReverseProxy2"));
37+
```
38+
or
39+
```c#
40+
41+
services.AddReverseProxy()
42+
.LoadFromMemory(routes, clusters)
43+
.LoadFromConfig(Configuration.GetSection("ReverseProxy"));
44+
```
45+
46+
## Configuration contract
47+
File-based configuration is dynamically mapped to the types in [Yarp.ReverseProxy.Configuration](xref:Yarp.ReverseProxy.Configuration) namespace by an [IProxyConfigProvider](xref:Yarp.ReverseProxy.Configuration.IProxyConfigProvider) implementation converts at application start and each time the configuration changes.
48+
49+
## Configuration Structure
50+
The configuration consists of a named section that you specified above via `Configuration.GetSection("ReverseProxy")`, and contains subsections for routes and clusters.
51+
52+
Example:
53+
```JSON
54+
{
55+
"ReverseProxy": {
56+
"Routes": {
57+
"route1" : {
58+
"ClusterId": "cluster1",
59+
"Match": {
60+
"Path": "{**catch-all}",
61+
"Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"]
62+
}
63+
}
64+
},
65+
"Clusters": {
66+
"cluster1": {
67+
"Destinations": {
68+
"cluster1/destination1": {
69+
"Address": "https://example.com/"
70+
}
71+
}
72+
}
73+
}
74+
}
75+
}
76+
```
77+
78+
### Routes
79+
80+
The routes section is an unordered collection of route matches and their associated configuration. A route requires at least the following fields:
81+
- RouteId - a unique name
82+
- ClusterId - refers to the name of an entry in the clusters section.
83+
- Match - contains either a Hosts array or a Path pattern string. Path is an ASP.NET Core route template that can be defined as [explained here](https://docs.microsoft.com/aspnet/core/fundamentals/routing#route-templates).
84+
Route matching is based on the most specific routes having highest precedence as described [here]( https://docs.microsoft.com/aspnet/core/fundamentals/routing#url-matching). Explicit ordering can be achieved using the `order` field, with lower values taking higher priority.
85+
86+
[Headers](header-routing.md), [Authorization](authn-authz.md), [CORS](cors.md), and other route based policies can be configured on each route entry. For additional fields see [RouteConfig](xref:Yarp.ReverseProxy.Configuration.RouteConfig).
87+
88+
The proxy will apply the given matching criteria and policies, and then pass off the request to the specified cluster.
89+
90+
### Clusters
91+
The clusters section is an unordered collection of named clusters. A cluster primarily contains a collection of named destinations and their addresses, any of which is considered capable of handling requests for a given route. The proxy will process the request according to the route and cluster configuration in order to select a destination.
92+
93+
For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.ClusterConfig).
94+
95+
## All config properties
96+
```JSON
97+
{
98+
// Base URLs the server listens on, must be configured independently of the routes below
99+
"Urls": "http://localhost:5000;https://localhost:5001",
100+
"Logging": {
101+
"LogLevel": {
102+
"Default": "Information",
103+
// Uncomment to hide diagnostic messages from runtime and proxy
104+
// "Microsoft": "Warning",
105+
// "Yarp" : "Warning",
106+
"Microsoft.Hosting.Lifetime": "Information"
107+
}
108+
},
109+
"ReverseProxy": {
110+
// Routes tell the proxy which requests to forward
111+
"Routes": {
112+
"minimumroute" : {
113+
// Matches anything and routes it to www.example.com
114+
"ClusterId": "minimumcluster",
115+
"Match": {
116+
"Path": "{**catch-all}"
117+
}
118+
},
119+
"allrouteprops" : {
120+
// matches /something/* and routes to "allclusterprops"
121+
"ClusterId": "allclusterprops", // Name of one of the clusters
122+
"Order" : 100, // Lower numbers have higher precedence
123+
"MaxRequestBodySize" : 1000000, // In bytes. An optional override of the server's limit (30MB default). Set to -1 to disable.
124+
"AuthorizationPolicy" : "Anonymous", // Name of the policy or "Default", "Anonymous"
125+
"CorsPolicy" : "Default", // Name of the CorsPolicy to apply to this route or "Default", "Disable"
126+
"Match": {
127+
"Path": "/something/{**remainder}", // The path to match using ASP.NET syntax.
128+
"Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"], // The host names to match, unspecified is any
129+
"Methods" : [ "GET", "PUT" ], // The HTTP methods that match, uspecified is all
130+
"Headers": [ // The headers to match, unspecified is any
131+
{
132+
"Name": "MyCustomHeader", // Name of the header
133+
"Values": [ "value1", "value2", "another value" ], // Matches are against any of these values
134+
"Mode": "ExactHeader", // or "HeaderPrefix", "Exists" , "Contains", "NotContains", "NotExists"
135+
"IsCaseSensitive": true
136+
}
137+
],
138+
"QueryParameters": [ // The query parameters to match, unspecified is any
139+
{
140+
"Name": "MyQueryParameter", // Name of the query parameter
141+
"Values": [ "value1", "value2", "another value" ], // Matches are against any of these values
142+
"Mode": "Exact", // or "Prefix", "Exists" , "Contains", "NotContains"
143+
"IsCaseSensitive": true
144+
}
145+
]
146+
},
147+
"Metadata" : { // List of key value pairs that can be used by custom extensions
148+
"MyName" : "MyValue"
149+
},
150+
"Transforms" : [ // List of transforms. See the Transforms article for more details
151+
{
152+
"RequestHeader": "MyHeader",
153+
"Set": "MyValue"
154+
}
155+
]
156+
}
157+
},
158+
// Clusters tell the proxy where and how to forward requests
159+
"Clusters": {
160+
"minimumcluster": {
161+
"Destinations": {
162+
"example.com": {
163+
"Address": "http://www.example.com/"
164+
}
165+
}
166+
},
167+
"allclusterprops": {
168+
"Destinations": {
169+
"first_destination": {
170+
"Address": "https://contoso.com"
171+
},
172+
"another_destination": {
173+
"Address": "https://10.20.30.40",
174+
"Health" : "https://10.20.30.40:12345/test" // override for active health checks
175+
}
176+
},
177+
"LoadBalancingPolicy" : "PowerOfTwoChoices", // Alternatively "FirstAlphabetical", "Random", "RoundRobin", "LeastRequests"
178+
"SessionAffinity": {
179+
"Enabled": true, // Defaults to 'false'
180+
"Policy": "Cookie", // Default, alternatively "CustomHeader"
181+
"FailurePolicy": "Redistribute", // default, Alternatively "Return503Error"
182+
"Settings" : {
183+
"CustomHeaderName": "MySessionHeaderName" // Defaults to 'X-Yarp-Proxy-Affinity`
184+
}
185+
},
186+
"HealthCheck": {
187+
"Active": { // Makes API calls to validate the health.
188+
"Enabled": "true",
189+
"Interval": "00:00:10",
190+
"Timeout": "00:00:10",
191+
"Policy": "ConsecutiveFailures",
192+
"Path": "/api/health", // API endpoint to query for health state
193+
"Query": "?foo=bar"
194+
},
195+
"Passive": { // Disables destinations based on HTTP response codes
196+
"Enabled": true, // Defaults to false
197+
"Policy" : "TransportFailureRateHealthPolicy", // Required
198+
"ReactivationPeriod" : "00:00:10" // 10s
199+
}
200+
},
201+
"HttpClient" : { // Configuration of HttpClient instance used to contact destinations
202+
"SSLProtocols" : "Tls13",
203+
"DangerousAcceptAnyServerCertificate" : false,
204+
"MaxConnectionsPerServer" : 1024,
205+
"EnableMultipleHttp2Connections" : true,
206+
"RequestHeaderEncoding" : "Latin1", // How to interpret non ASCII characters in request header values
207+
"ResponseHeaderEncoding" : "Latin1" // How to interpret non ASCII characters in response header values
208+
},
209+
"HttpRequest" : { // Options for sending request to destination
210+
"ActivityTimeout" : "00:02:00",
211+
"Version" : "2",
212+
"VersionPolicy" : "RequestVersionOrLower",
213+
"AllowResponseBuffering" : "false"
214+
},
215+
"Metadata" : { // Custom Key value pairs
216+
"TransportFailureRateHealthPolicy.RateLimit": "0.5", // Used by Passive health policy
217+
"MyKey" : "MyValue"
218+
}
219+
}
220+
}
221+
}
222+
}
223+
```
224+
225+
For more information see [logging configuration](diagnosing-yarp-issues.md#logging) and [HTTP client configuration](http-client-config.md).

0 commit comments

Comments
 (0)