mirror of
https://github.com/nsnail/Ocelot.git
synced 2025-06-19 16:18:14 +08:00
Rename all ReRoute to Route to move closer to YARP +semver: breaking
This commit is contained in:
Tom Pallister
@ -1,7 +1,7 @@
|
||||
Authentication
|
||||
==============
|
||||
|
||||
In order to authenticate ReRoutes and subsequently use any of Ocelot's claims based features such as authorisation or modifying the request with values from the token. Users must register authentication services in their Startup.cs as usual but they provide a scheme (authentication provider key) with each registration e.g.
|
||||
In order to authenticate Routes and subsequently use any of Ocelot's claims based features such as authorisation or modifying the request with values from the token. Users must register authentication services in their Startup.cs as usual but they provide a scheme (authentication provider key) with each registration e.g.
|
||||
|
||||
.. code-block:: csharp
|
||||
|
||||
@ -16,11 +16,11 @@ In order to authenticate ReRoutes and subsequently use any of Ocelot's claims ba
|
||||
}
|
||||
|
||||
|
||||
In this example TestKey is the scheme that this provider has been registered with. We then map this to a ReRoute in the configuration e.g.
|
||||
In this example TestKey is the scheme that this provider has been registered with. We then map this to a Route in the configuration e.g.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"ReRoutes": [{
|
||||
"Routes": [{
|
||||
"DownstreamHostAndPorts": [
|
||||
{
|
||||
"Host": "localhost",
|
||||
@ -30,7 +30,7 @@ In this example TestKey is the scheme that this provider has been registered wit
|
||||
"DownstreamPathTemplate": "/",
|
||||
"UpstreamPathTemplate": "/",
|
||||
"UpstreamHttpMethod": ["Post"],
|
||||
"ReRouteIsCaseSensitive": false,
|
||||
"RouteIsCaseSensitive": false,
|
||||
"DownstreamScheme": "http",
|
||||
"AuthenticationOptions": {
|
||||
"AuthenticationProviderKey": "TestKey",
|
||||
@ -38,9 +38,9 @@ In this example TestKey is the scheme that this provider has been registered wit
|
||||
}
|
||||
}]
|
||||
|
||||
When Ocelot runs it will look at this ReRoutes AuthenticationOptions.AuthenticationProviderKey and check that there is an Authentication provider registered with the given key. If there isn't then Ocelot will not start up, if there is then the ReRoute will use that provider when it executes.
|
||||
When Ocelot runs it will look at this Routes AuthenticationOptions.AuthenticationProviderKey and check that there is an Authentication provider registered with the given key. If there isn't then Ocelot will not start up, if there is then the Route will use that provider when it executes.
|
||||
|
||||
If a ReRoute is authenticated Ocelot will invoke whatever scheme is associated with it while executing the authentication middleware. If the request fails authentication Ocelot returns a http status code 401.
|
||||
If a Route is authenticated Ocelot will invoke whatever scheme is associated with it while executing the authentication middleware. If the request fails authentication Ocelot returns a http status code 401.
|
||||
|
||||
JWT Tokens
|
||||
^^^^^^^^^^
|
||||
@ -63,11 +63,11 @@ If you want to authenticate using JWT tokens maybe from a provider like Auth0 yo
|
||||
services.AddOcelot();
|
||||
}
|
||||
|
||||
Then map the authentication provider key to a ReRoute in your configuration e.g.
|
||||
Then map the authentication provider key to a Route in your configuration e.g.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"ReRoutes": [{
|
||||
"Routes": [{
|
||||
"DownstreamHostAndPorts": [
|
||||
{
|
||||
"Host": "localhost",
|
||||
@ -77,7 +77,7 @@ Then map the authentication provider key to a ReRoute in your configuration e.g.
|
||||
"DownstreamPathTemplate": "/",
|
||||
"UpstreamPathTemplate": "/",
|
||||
"UpstreamHttpMethod": ["Post"],
|
||||
"ReRouteIsCaseSensitive": false,
|
||||
"RouteIsCaseSensitive": false,
|
||||
"DownstreamScheme": "http",
|
||||
"AuthenticationOptions": {
|
||||
"AuthenticationProviderKey": "TestKey",
|
||||
@ -111,11 +111,11 @@ In order to use IdentityServer bearer tokens, register your IdentityServer servi
|
||||
services.AddOcelot();
|
||||
}
|
||||
|
||||
Then map the authentication provider key to a ReRoute in your configuration e.g.
|
||||
Then map the authentication provider key to a Route in your configuration e.g.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"ReRoutes": [{
|
||||
"Routes": [{
|
||||
"DownstreamHostAndPorts": [
|
||||
{
|
||||
"Host": "localhost",
|
||||
@ -125,7 +125,7 @@ Then map the authentication provider key to a ReRoute in your configuration e.g.
|
||||
"DownstreamPathTemplate": "/",
|
||||
"UpstreamPathTemplate": "/",
|
||||
"UpstreamHttpMethod": ["Post"],
|
||||
"ReRouteIsCaseSensitive": false,
|
||||
"RouteIsCaseSensitive": false,
|
||||
"DownstreamScheme": "http",
|
||||
"AuthenticationOptions": {
|
||||
"AuthenticationProviderKey": "TestKey",
|
||||
@ -176,4 +176,4 @@ Allowed Scopes
|
||||
|
||||
If you add scopes to AllowedScopes Ocelot will get all the user claims (from the token) of the type scope and make sure that the user has all of the scopes in the list.
|
||||
|
||||
This is a way to restrict access to a ReRoute on a per scope basis.
|
||||
This is a way to restrict access to a Route on a per scope basis.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
Authorisation
|
||||
=============
|
||||
|
||||
Ocelot supports claims based authorisation which is run post authentication. This means if you have a route you want to authorise you can add the following to you ReRoute configuration.
|
||||
Ocelot supports claims based authorisation which is run post authentication. This means if you have a route you want to authorise you can add the following to you Route configuration.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
||||
@ -21,7 +21,7 @@ The second thing you need to do something like the following to your ConfigureSe
|
||||
x.WithDictionaryHandle();
|
||||
})
|
||||
|
||||
Finally in order to use caching on a route in your ReRoute configuration add this setting.
|
||||
Finally in order to use caching on a route in your Route configuration add this setting.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ Ocelot allows the user to access claims and transform them into headers, query s
|
||||
|
||||
After the user is authenticated we run the claims to claims transformation middleware. This allows the user to transform claims before the authorisation middleware is called. After the user is authorised first we call the claims to headers middleware, thenthe claims to query string parameters middleware, and Finally the claims to downstream pathmiddleware.
|
||||
|
||||
The syntax for performing the transforms is the same for each process. In the ReRoute configuration a json dictionary is added with a specific name either AddClaimsToRequest, AddHeadersToRequest, AddQueriesToRequest, or ChangeDownstreamPathTemplate.
|
||||
The syntax for performing the transforms is the same for each process. In the Route configuration a json dictionary is added with a specific name either AddClaimsToRequest, AddHeadersToRequest, AddQueriesToRequest, or ChangeDownstreamPathTemplate.
|
||||
|
||||
Note: I'm not a hotshot programmer so have no idea if this syntax is good...
|
||||
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
Configuration
|
||||
============
|
||||
|
||||
An example configuration can be found `here <https://github.com/ThreeMammals/Ocelot/blob/master/test/Ocelot.ManualTest/ocelot.json>`_. There are two sections to the configuration. An array of ReRoutes and a GlobalConfiguration. The ReRoutes are the objects that tell Ocelot how to treat an upstream request. The Global configuration is a bit hacky and allows overrides of ReRoute specific settings. It's useful if you don't want to manage lots of ReRoute specific settings.
|
||||
An example configuration can be found `here <https://github.com/ThreeMammals/Ocelot/blob/master/test/Ocelot.ManualTest/ocelot.json>`_. There are two sections to the configuration. An array of Routes and a GlobalConfiguration. The Routes are the objects that tell Ocelot how to treat an upstream request. The Global configuration is a bit hacky and allows overrides of Route specific settings. It's useful if you don't want to manage lots of Route specific settings.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [],
|
||||
"Routes": [],
|
||||
"GlobalConfiguration": {}
|
||||
}
|
||||
|
||||
Here is an example ReRoute configuration, You don't need to set all of these things but this is everything that is available at the moment:
|
||||
Here is an example Route configuration, You don't need to set all of these things but this is everything that is available at the moment:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -31,7 +31,7 @@ Here is an example ReRoute configuration, You don't need to set all of these thi
|
||||
"TtlSeconds": 0,
|
||||
"Region": ""
|
||||
},
|
||||
"ReRouteIsCaseSensitive": false,
|
||||
"RouteIsCaseSensitive": false,
|
||||
"ServiceName": "",
|
||||
"DownstreamScheme": "http",
|
||||
"DownstreamHostAndPorts": [
|
||||
@ -112,7 +112,7 @@ Instead of adding the configuration directly e.g. AddJsonFile("ocelot.json") you
|
||||
|
||||
In this scenario Ocelot will look for any files that match the pattern (?i)ocelot.([a-zA-Z0-9]*).json and then merge these together. If you want to set the GlobalConfiguration property you must have a file called ocelot.global.json.
|
||||
|
||||
The way Ocelot merges the files is basically load them, loop over them, add any ReRoutes, add any AggregateReRoutes and if the file is called ocelot.global.json add the GlobalConfiguration aswell as any ReRoutes or AggregateReRoutes. Ocelot will then save the merged configuration to a file called ocelot.json and this will be used as the source of truth while ocelot is running.
|
||||
The way Ocelot merges the files is basically load them, loop over them, add any Routes, add any AggregateRoutes and if the file is called ocelot.global.json add the GlobalConfiguration aswell as any Routes or AggregateRoutes. Ocelot will then save the merged configuration to a file called ocelot.json and this will be used as the source of truth while ocelot is running.
|
||||
|
||||
At the moment there is no validation at this stage it only happens when Ocelot validates the final merged configuration. This is something to be aware of when you are investigating problems. I would advise always checking what is in ocelot.json if you have any problems.
|
||||
|
||||
@ -195,7 +195,7 @@ If you do not set the ConfigurationKey Ocelot will use the string InternalConfig
|
||||
Follow Redirects / Use CookieContainer
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Use HttpHandlerOptions in ReRoute configuration to set up HttpHandler behavior:
|
||||
Use HttpHandlerOptions in Route configuration to set up HttpHandler behavior:
|
||||
|
||||
1. AllowAutoRedirect is a value that indicates whether the request should follow redirection responses. Set it true if the request should automatically follow redirection responses from the Downstream resource; otherwise false. The default value is false.
|
||||
|
||||
@ -204,7 +204,7 @@ Use HttpHandlerOptions in ReRoute configuration to set up HttpHandler behavior:
|
||||
SSL Errors
|
||||
^^^^^^^^^^
|
||||
|
||||
If you want to ignore SSL warnings / errors set the following in your ReRoute config.
|
||||
If you want to ignore SSL warnings / errors set the following in your Route config.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -215,7 +215,7 @@ I don't recommend doing this, I suggest creating your own certificate and then g
|
||||
MaxConnectionsPerServer
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This controls how many connections the internal HttpClient will open. This can be set at ReRoute or global level.
|
||||
This controls how many connections the internal HttpClient will open. This can be set at Route or global level.
|
||||
|
||||
React to Configuration Changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -31,8 +31,8 @@ Next you must add the handlers to Ocelot's container like below...
|
||||
.AddDelegatingHandler<FakeHandler>()
|
||||
.AddDelegatingHandler<FakeHandlerTwo>()
|
||||
|
||||
Both of these Add methods have a default parameter called global which is set to false. If it is false then the intent of the DelegatingHandler is to be applied to specific ReRoutes via ocelot.json (more on that later). If it is set to true
|
||||
then it becomes a global handler and will be applied to all ReRoutes.
|
||||
Both of these Add methods have a default parameter called global which is set to false. If it is false then the intent of the DelegatingHandler is to be applied to specific Routes via ocelot.json (more on that later). If it is set to true
|
||||
then it becomes a global handler and will be applied to all Routes.
|
||||
|
||||
e.g.
|
||||
|
||||
@ -43,7 +43,7 @@ As below...
|
||||
services.AddOcelot()
|
||||
.AddDelegatingHandler<FakeHandler>(true)
|
||||
|
||||
Finally if you want ReRoute specific DelegatingHandlers or to order your specific and / or global (more on this later) DelegatingHandlers then you must add the following json to the specific ReRoute in ocelot.json. The names in the array must match the class names of your
|
||||
Finally if you want Route specific DelegatingHandlers or to order your specific and / or global (more on this later) DelegatingHandlers then you must add the following json to the specific Route in ocelot.json. The names in the array must match the class names of your
|
||||
DelegatingHandlers for Ocelot to match them together.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -8,7 +8,7 @@ Add to Request
|
||||
|
||||
This feature was requestes in `GitHub #313 <https://github.com/ThreeMammals/Ocelot/issues/313>`_.
|
||||
|
||||
If you want to add a header to your upstream request please add the following to a ReRoute in your ocelot.json:
|
||||
If you want to add a header to your upstream request please add the following to a Route in your ocelot.json:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -25,7 +25,7 @@ Add to Response
|
||||
|
||||
This feature was requested in `GitHub #280 <https://github.com/ThreeMammals/Ocelot/issues/280>`_.
|
||||
|
||||
If you want to add a header to your downstream response please add the following to a ReRoute in ocelot.json..
|
||||
If you want to add a header to your downstream response please add the following to a Route in ocelot.json..
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -33,7 +33,7 @@ If you want to add a header to your downstream response please add the following
|
||||
"Uncle": "Bob"
|
||||
},
|
||||
|
||||
In the example above a header with the key Uncle and value Bob would be returned by Ocelot when requesting the specific ReRoute.
|
||||
In the example above a header with the key Uncle and value Bob would be returned by Ocelot when requesting the specific Route.
|
||||
|
||||
If you want to return the Butterfly APM trace id then do something like the following..
|
||||
|
||||
@ -57,7 +57,7 @@ The key is "Test" and the value is "http://www.bbc.co.uk/, http://ocelot.com/".
|
||||
Pre Downstream Request
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Add the following to a ReRoute in ocelot.json in order to replace http://www.bbc.co.uk/ with http://ocelot.com/. This header will be changed before the request downstream and will be sent to the downstream server.
|
||||
Add the following to a Route in ocelot.json in order to replace http://www.bbc.co.uk/ with http://ocelot.com/. This header will be changed before the request downstream and will be sent to the downstream server.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -68,7 +68,7 @@ Add the following to a ReRoute in ocelot.json in order to replace http://www.bbc
|
||||
Post Downstream Request
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Add the following to a ReRoute in ocelot.json in order to replace http://www.bbc.co.uk/ with http://ocelot.com/. This transformation will take place after Ocelot has received the response from the downstream service.
|
||||
Add the following to a Route in ocelot.json in order to replace http://www.bbc.co.uk/ with http://ocelot.com/. This transformation will take place after Ocelot has received the response from the downstream service.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
||||
@ -30,13 +30,13 @@ You can replicate a Permissive. Using RBAC role bindings.
|
||||
.. code-block::bash
|
||||
kubectl create clusterrolebinding permissive-binding --clusterrole=cluster-admin --user=admin --user=kubelet --group=system:serviceaccounts
|
||||
|
||||
The following example shows how to set up a ReRoute that will work in kubernetes. The most important thing is the ServiceName which is made up of the kubernetes service name. We also need to set up the ServiceDiscoveryProvider in GlobalConfiguration. The example here shows a typical configuration.
|
||||
The following example shows how to set up a Route that will work in kubernetes. The most important thing is the ServiceName which is made up of the kubernetes service name. We also need to set up the ServiceDiscoveryProvider in GlobalConfiguration. The example here shows a typical configuration.
|
||||
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/api/values",
|
||||
"DownstreamScheme": "http",
|
||||
@ -76,13 +76,13 @@ The polling interval is in milliseconds and tells Ocelot how often to call kuber
|
||||
|
||||
Please note there are tradeoffs here. If you poll kubernetes it is possible Ocelot will not know if a service is down depending on your polling interval and you might get more errors than if you get the latest services per request. This really depends on how volatile your services are. I doubt it will matter for most people and polling may give a tiny performance improvement over calling kubernetes per request. There is no way for Ocelot to work these out for you.
|
||||
|
||||
If your downstream service resides in a different namespace you can override the global setting at the ReRoute level by specifying a ServiceNamespace.
|
||||
If your downstream service resides in a different namespace you can override the global setting at the Route level by specifying a ServiceNamespace.
|
||||
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/api/values",
|
||||
"DownstreamScheme": "http",
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
Load Balancer
|
||||
=============
|
||||
|
||||
Ocelot can load balance across available downstream services for each ReRoute. This means you can scale your downstream services and Ocelot can use them effectively.
|
||||
Ocelot can load balance across available downstream services for each Route. This means you can scale your downstream services and Ocelot can use them effectively.
|
||||
|
||||
The type of load balancer available are:
|
||||
|
||||
@ -18,7 +18,7 @@ You must choose in your configuration which load balancer to use.
|
||||
Configuration
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The following shows how to set up multiple downstream services for a ReRoute using ocelot.json and then select the LeastConnection load balancer. This is the simplest way to get load balancing set up.
|
||||
The following shows how to set up multiple downstream services for a Route using ocelot.json and then select the LeastConnection load balancer. This is the simplest way to get load balancing set up.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -46,7 +46,7 @@ The following shows how to set up multiple downstream services for a ReRoute usi
|
||||
Service Discovery
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following shows how to set up a ReRoute using service discovery then select the LeastConnection load balancer.
|
||||
The following shows how to set up a Route using service discovery then select the LeastConnection load balancer.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -97,7 +97,7 @@ In order to set up CookieStickySessions load balancer you need to do something l
|
||||
|
||||
The LoadBalancerOptions are Type this needs to be CookieStickySessions, Key this is the key of the cookie you wish to use for the sticky sessions, Expiry this is how long in milliseconds you want to the session to be stuck for. Remember this refreshes on every request which is meant to mimick how sessions work usually.
|
||||
|
||||
If you have multiple ReRoutes with the same LoadBalancerOptions then all of those ReRoutes will use the same load balancer for there subsequent requests. This means the sessions will be stuck across ReRoutes.
|
||||
If you have multiple Routes with the same LoadBalancerOptions then all of those Routes will use the same load balancer for there subsequent requests. This means the sessions will be stuck across Routes.
|
||||
|
||||
Please note that if you give more than one DownstreamHostAndPort or you are using a Service Discovery provider such as Consul and this returns more than one service then CookieStickySessions uses round robin to select the next server. This is hard coded at the moment but could be changed.
|
||||
|
||||
@ -172,7 +172,7 @@ Finally you need to register this class with Ocelot. I have used the most comple
|
||||
|
||||
.. code-block:: csharp
|
||||
|
||||
Func<IServiceProvider, DownstreamReRoute, IServiceDiscoveryProvider, CustomLoadBalancer> loadBalancerFactoryFunc = (serviceProvider, reRoute, serviceDiscoveryProvider) => new CustomLoadBalancer(serviceDiscoveryProvider.Get);
|
||||
Func<IServiceProvider, DownstreamRoute, IServiceDiscoveryProvider, CustomLoadBalancer> loadBalancerFactoryFunc = (serviceProvider, Route, serviceDiscoveryProvider) => new CustomLoadBalancer(serviceDiscoveryProvider.Get);
|
||||
|
||||
s.AddOcelot()
|
||||
.AddCustomLoadBalancer(loadBalancerFactoryFunc);
|
||||
@ -198,11 +198,11 @@ There are numerous extension methods to add a custom load balancer and the inter
|
||||
where T : ILoadBalancer;
|
||||
|
||||
IOcelotBuilder AddCustomLoadBalancer<T>(
|
||||
Func<DownstreamReRoute, IServiceDiscoveryProvider, T> loadBalancerFactoryFunc)
|
||||
Func<DownstreamRoute, IServiceDiscoveryProvider, T> loadBalancerFactoryFunc)
|
||||
where T : ILoadBalancer;
|
||||
|
||||
IOcelotBuilder AddCustomLoadBalancer<T>(
|
||||
Func<IServiceProvider, DownstreamReRoute, IServiceDiscoveryProvider, T> loadBalancerFactoryFunc)
|
||||
Func<IServiceProvider, DownstreamRoute, IServiceDiscoveryProvider, T> loadBalancerFactoryFunc)
|
||||
where T : ILoadBalancer;
|
||||
|
||||
When you enable custom load balancers Ocelot looks up your load balancer by its class name when it decides if it should do load balancing. If it finds a match it will use your load balaner to load balance. If Ocelot cannot match the load balancer type in your configuration with the name of registered load balancer class then you will receive a HTTP 500 internal server error. If your load balancer factory throw an exception when Ocelot calls it you will receive a HTTP 500 internal server error.
|
||||
|
||||
@ -3,7 +3,7 @@ HTTP Method Transformation
|
||||
|
||||
Ocelot allows the user to change the HTTP request method that will be used when making a request to a downstream service.
|
||||
|
||||
This achieved by setting the following ReRoute configuration:
|
||||
This achieved by setting the following Route configuration:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -23,6 +23,6 @@ This achieved by setting the following ReRoute configuration:
|
||||
],
|
||||
}
|
||||
|
||||
The key property here is DownstreamHttpMethod which is set as POST and the ReRoute will only match on GET as set by UpstreamHttpMethod.
|
||||
The key property here is DownstreamHttpMethod which is set as POST and the Route will only match on GET as set by UpstreamHttpMethod.
|
||||
|
||||
This feature can be useful when interacting with downstream apis that only support POST and you want to present some kind of RESTful interface.
|
||||
@ -1,7 +1,7 @@
|
||||
Quality of Service
|
||||
==================
|
||||
|
||||
Ocelot supports one QoS capability at the current time. You can set on a per ReRoute basis if you want to use a circuit breaker when making requests to a downstream service. This uses an awesome
|
||||
Ocelot supports one QoS capability at the current time. You can set on a per Route basis if you want to use a circuit breaker when making requests to a downstream service. This uses an awesome
|
||||
.NET library called Polly check them out `here <https://github.com/App-vNext/Polly>`_.
|
||||
|
||||
The first thing you need to do if you want to use the administration API is bring in the relevant NuGet package..
|
||||
@ -19,7 +19,7 @@ Then in your ConfigureServices method
|
||||
.AddPolly();
|
||||
}
|
||||
|
||||
Then add the following section to a ReRoute configuration.
|
||||
Then add the following section to a Route configuration.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ Thanks to `@catcherwong article <http://www.c-sharpcorner.com/article/building-a
|
||||
|
||||
Ocelot supports rate limiting of upstream requests so that your downstream services do not become overloaded. This feature was added by @geffzhang on GitHub! Thanks very much.
|
||||
|
||||
OK so to get rate limiting working for a ReRoute you need to add the following json to it.
|
||||
OK so to get rate limiting working for a Route you need to add the following json to it.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
Request Aggregation
|
||||
===================
|
||||
|
||||
Ocelot allows you to specify Aggregate ReRoutes that compose multiple normal ReRoutes and map their responses into one object. This is usually where you have
|
||||
Ocelot allows you to specify Aggregate Routes that compose multiple normal Routes and map their responses into one object. This is usually where you have
|
||||
a client that is making multiple requests to a server where it could just be one. This feature allows you to start implementing back end for a front end type
|
||||
architecture with Ocelot.
|
||||
|
||||
This feature was requested as part of `Issue 79 <https://github.com/ThreeMammals/Ocelot/pull/79>`_ and further improvements were made as part of `Issue 298 <https://github.com/ThreeMammals/Ocelot/issue/298>`_.
|
||||
|
||||
In order to set this up you must do something like the following in your ocelot.json. Here we have specified two normal ReRoutes and each one has a Key property.
|
||||
We then specify an Aggregate that composes the two ReRoutes using their keys in the ReRouteKeys list and says then we have the UpstreamPathTemplate which works like a normal ReRoute.
|
||||
Obviously you cannot have duplicate UpstreamPathTemplates between ReRoutes and Aggregates. You can use all of Ocelot's normal ReRoute options apart from RequestIdKey (explained in gotchas below).
|
||||
In order to set this up you must do something like the following in your ocelot.json. Here we have specified two normal Routes and each one has a Key property.
|
||||
We then specify an Aggregate that composes the two Routes using their keys in the RouteKeys list and says then we have the UpstreamPathTemplate which works like a normal Route.
|
||||
Obviously you cannot have duplicate UpstreamPathTemplates between Routes and Aggregates. You can use all of Ocelot's normal Route options apart from RequestIdKey (explained in gotchas below).
|
||||
|
||||
Advanced register your own Aggregators
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -22,7 +22,7 @@ The ocelot.json setup is pretty much the same as the basic aggregation approach
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/",
|
||||
"UpstreamPathTemplate": "/laura",
|
||||
@ -56,7 +56,7 @@ The ocelot.json setup is pretty much the same as the basic aggregation approach
|
||||
],
|
||||
"Aggregates": [
|
||||
{
|
||||
"ReRouteKeys": [
|
||||
"RouteKeys": [
|
||||
"Tom",
|
||||
"Laura"
|
||||
],
|
||||
@ -66,7 +66,7 @@ The ocelot.json setup is pretty much the same as the basic aggregation approach
|
||||
]
|
||||
}
|
||||
|
||||
Here we have added an aggregator called FakeDefinedAggregator. Ocelot is going to look for this aggregator when it tries to aggregate this ReRoute.
|
||||
Here we have added an aggregator called FakeDefinedAggregator. Ocelot is going to look for this aggregator when it tries to aggregate this Route.
|
||||
|
||||
In order to make the aggregator available we must add the FakeDefinedAggregator to the OcelotBuilder like below.
|
||||
|
||||
@ -76,7 +76,7 @@ In order to make the aggregator available we must add the FakeDefinedAggregator
|
||||
.AddOcelot()
|
||||
.AddSingletonDefinedAggregator<FakeDefinedAggregator>();
|
||||
|
||||
Now when Ocelot tries to aggregate the ReRoute above it will find the FakeDefinedAggregator in the container and use it to aggregate the ReRoute.
|
||||
Now when Ocelot tries to aggregate the Route above it will find the FakeDefinedAggregator in the container and use it to aggregate the Route.
|
||||
Because the FakeDefinedAggregator is registered in the container you can add any dependencies it needs into the container like below.
|
||||
|
||||
.. code-block:: csharp
|
||||
@ -106,7 +106,7 @@ In order to make an Aggregator you must implement this interface.
|
||||
Task<DownstreamResponse> Aggregate(List<HttpContext> responses);
|
||||
}
|
||||
|
||||
With this feature you can pretty much do whatever you want because the HttpContext objects contain the results of all the aggregate requests. Please note if the HttpClient throws an exception when making a request to a ReRoute in the aggregate then you will not get a HttpContext for it but you would for any that succeed. If it does throw an exception this will be logged.
|
||||
With this feature you can pretty much do whatever you want because the HttpContext objects contain the results of all the aggregate requests. Please note if the HttpClient throws an exception when making a request to a Route in the aggregate then you will not get a HttpContext for it but you would for any that succeed. If it does throw an exception this will be logged.
|
||||
|
||||
Basic expecting JSON from Downstream Services
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -114,7 +114,7 @@ Basic expecting JSON from Downstream Services
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/",
|
||||
"UpstreamPathTemplate": "/laura",
|
||||
@ -148,7 +148,7 @@ Basic expecting JSON from Downstream Services
|
||||
],
|
||||
"Aggregates": [
|
||||
{
|
||||
"ReRouteKeys": [
|
||||
"RouteKeys": [
|
||||
"Tom",
|
||||
"Laura"
|
||||
],
|
||||
@ -157,16 +157,16 @@ Basic expecting JSON from Downstream Services
|
||||
]
|
||||
}
|
||||
|
||||
You can also set UpstreamHost and ReRouteIsCaseSensitive in the Aggregate configuration. These behave the same as any other ReRoutes.
|
||||
You can also set UpstreamHost and RouteIsCaseSensitive in the Aggregate configuration. These behave the same as any other Routes.
|
||||
|
||||
If the ReRoute /tom returned a body of {"Age": 19} and /laura returned {"Age": 25} the the response after aggregation would be as follows.
|
||||
If the Route /tom returned a body of {"Age": 19} and /laura returned {"Age": 25} the the response after aggregation would be as follows.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{"Tom":{"Age": 19},"Laura":{"Age": 25}}
|
||||
|
||||
At the moment the aggregation is very simple. Ocelot just gets the response from your downstream service and sticks it into a json dictionary
|
||||
as above. With the ReRoute key being the key of the dictionary and the value the response body from your downstream service. You can see that the object is just
|
||||
as above. With the Route key being the key of the dictionary and the value the response body from your downstream service. You can see that the object is just
|
||||
JSON without any pretty spaces etc.
|
||||
|
||||
All headers will be lost from the downstream services response.
|
||||
@ -179,7 +179,7 @@ It will not change the aggregate response into a 404 even if all the downstreams
|
||||
Gotcha's / Further info
|
||||
-----------------------
|
||||
|
||||
You cannot use ReRoutes with specific RequestIdKeys as this would be crazy complicated to track.
|
||||
You cannot use Routes with specific RequestIdKeys as this would be crazy complicated to track.
|
||||
|
||||
Aggregation only supports the GET HTTP Verb.
|
||||
|
||||
|
||||
@ -18,19 +18,19 @@ In your ocelot.json set the following in the GlobalConfiguration section. This w
|
||||
"RequestIdKey": "OcRequestId"
|
||||
}
|
||||
|
||||
I recommend using the GlobalConfiguration unless you really need it to be ReRoute specific.
|
||||
I recommend using the GlobalConfiguration unless you really need it to be Route specific.
|
||||
|
||||
*ReRoute*
|
||||
*Route*
|
||||
|
||||
If you want to override this for a specific ReRoute add the following to ocelot.json for the specific ReRoute.
|
||||
If you want to override this for a specific Route add the following to ocelot.json for the specific Route.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"RequestIdKey": "OcRequestId"
|
||||
|
||||
Once Ocelot has identified the incoming requests matching ReRoute object it will set the request id based on the ReRoute configuration.
|
||||
Once Ocelot has identified the incoming requests matching Route object it will set the request id based on the Route configuration.
|
||||
|
||||
This can lead to a small gotcha. If you set a GlobalConfiguration it is possible to get one request id until the ReRoute is identified and then another after that because the request id key can change. This is by design and is the best solution I can think of at the moment. In this case the OcelotLogger will show the request id and previous request id in the logs.
|
||||
This can lead to a small gotcha. If you set a GlobalConfiguration it is possible to get one request id until the Route is identified and then another after that because the request id key can change. This is by design and is the best solution I can think of at the moment. In this case the OcelotLogger will show the request id and previous request id in the logs.
|
||||
|
||||
Below is an example of the logging when set at Debug level for a normal request..
|
||||
|
||||
@ -41,7 +41,7 @@ Below is an example of the logging when set at Debug level for a normal request.
|
||||
dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]
|
||||
requestId: asdf, previousRequestId: no previous request id, message: upstream url path is {upstreamUrlPath},
|
||||
dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]
|
||||
requestId: asdf, previousRequestId: no previous request id, message: downstream template is {downstreamRoute.Data.ReRoute.DownstreamPath},
|
||||
requestId: asdf, previousRequestId: no previous request id, message: downstream template is {downstreamRoute.Data.Route.DownstreamPath},
|
||||
dbug: Ocelot.RateLimit.Middleware.ClientRateLimitMiddleware[0]
|
||||
requestId: asdf, previousRequestId: no previous request id, message: EndpointRateLimiting is not enabled for Ocelot.Values.PathTemplate,
|
||||
dbug: Ocelot.Authorisation.Middleware.AuthorisationMiddleware[0]
|
||||
|
||||
@ -4,16 +4,16 @@ Routing
|
||||
Ocelot's primary functionality is to take incoming http requests and forward them on to a downstream service. Ocelot currently only supports this in the form of another http request (in the future
|
||||
this could be any transport mechanism).
|
||||
|
||||
Ocelot's describes the routing of one request to another as a ReRoute. In order to get anything working in Ocelot you need to set up a ReRoute in the configuration.
|
||||
Ocelot's describes the routing of one request to another as a Route. In order to get anything working in Ocelot you need to set up a Route in the configuration.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
]
|
||||
}
|
||||
|
||||
To configure a ReRoute you need to add one to the ReRoutes json array.
|
||||
To configure a Route you need to add one to the Routes json array.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -38,7 +38,7 @@ The UpstreamPathTemplate is the URL that Ocelot will use to identify which Downs
|
||||
|
||||
In Ocelot you can add placeholders for variables to your Templates in the form of {something}. The placeholder variable needs to be present in both the DownstreamPathTemplate and UpstreamPathTemplate properties. When it is Ocelot will attempt to substitute the value in the UpstreamPathTemplate placeholder into the DownstreamPathTemplate for each request Ocelot processes.
|
||||
|
||||
You can also do a catch all type of ReRoute e.g.
|
||||
You can also do a catch all type of Route e.g.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -60,11 +60,11 @@ This will forward any path + query string combinations to the downstream service
|
||||
|
||||
The default ReRouting configuration is case insensitive!
|
||||
|
||||
In order to change this you can specify on a per ReRoute basis the following setting.
|
||||
In order to change this you can specify on a per Route basis the following setting.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"ReRouteIsCaseSensitive": true
|
||||
"RouteIsCaseSensitive": true
|
||||
|
||||
This means that when Ocelot tries to match the incoming upstream url with an upstream template the
|
||||
evaluation will be case sensitive.
|
||||
@ -91,7 +91,7 @@ If you set up your config like below, all requests will be proxied straight thro
|
||||
"UpstreamHttpMethod": [ "Get" ]
|
||||
}
|
||||
|
||||
The catch all has a lower priority than any other ReRoute. If you also have the ReRoute below in your config then Ocelot would match it before the catch all.
|
||||
The catch all has a lower priority than any other Route. If you also have the Route below in your config then Ocelot would match it before the catch all.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -111,7 +111,7 @@ The catch all has a lower priority than any other ReRoute. If you also have the
|
||||
Upstream Host
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
This feature allows you to have ReRoutes based on the upstream host. This works by looking at the host header the client has used and then using this as part of the information we use to identify a ReRoute.
|
||||
This feature allows you to have Routes based on the upstream host. This works by looking at the host header the client has used and then using this as part of the information we use to identify a Route.
|
||||
|
||||
In order to use this feature please add the following to your config.
|
||||
|
||||
@ -131,16 +131,16 @@ In order to use this feature please add the following to your config.
|
||||
"UpstreamHost": "somedomain.com"
|
||||
}
|
||||
|
||||
The ReRoute above will only be matched when the host header value is somedomain.com.
|
||||
The Route above will only be matched when the host header value is somedomain.com.
|
||||
|
||||
If you do not set UpstreamHost on a ReRoute then any host header will match it. This means that if you have two ReRoutes that are the same, apart from the UpstreamHost, where one is null and the other set Ocelot will favour the one that has been set.
|
||||
If you do not set UpstreamHost on a Route then any host header will match it. This means that if you have two Routes that are the same, apart from the UpstreamHost, where one is null and the other set Ocelot will favour the one that has been set.
|
||||
|
||||
This feature was requested as part of `Issue 216 <https://github.com/ThreeMammals/Ocelot/pull/216>`_ .
|
||||
|
||||
Priority
|
||||
^^^^^^^^
|
||||
|
||||
You can define the order you want your ReRoutes to match the Upstream HttpRequest by including a "Priority" property in ocelot.json
|
||||
You can define the order you want your Routes to match the Upstream HttpRequest by including a "Priority" property in ocelot.json
|
||||
See `Issue 270 <https://github.com/ThreeMammals/Ocelot/pull/270>`_ for reference
|
||||
|
||||
.. code-block:: json
|
||||
@ -149,7 +149,7 @@ See `Issue 270 <https://github.com/ThreeMammals/Ocelot/pull/270>`_ for reference
|
||||
"Priority": 0
|
||||
}
|
||||
|
||||
0 is the lowest priority, Ocelot will always use 0 for /{catchAll} ReRoutes and this is still hardcoded. After that you are free to set any priority you wish.
|
||||
0 is the lowest priority, Ocelot will always use 0 for /{catchAll} Routes and this is still hardcoded. After that you are free to set any priority you wish.
|
||||
|
||||
e.g. you could have
|
||||
|
||||
@ -169,14 +169,14 @@ and
|
||||
"Priority": 1
|
||||
}
|
||||
|
||||
In the example above if you make a request into Ocelot on /goods/delete Ocelot will match /goods/delete ReRoute. Previously it would have matched /goods/{catchAll} (because this is the first ReRoute in the list!).
|
||||
In the example above if you make a request into Ocelot on /goods/delete Ocelot will match /goods/delete Route. Previously it would have matched /goods/{catchAll} (because this is the first Route in the list!).
|
||||
|
||||
Dynamic Routing
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
This feature was requested in `issue 340 <https://github.com/ThreeMammals/Ocelot/issues/340>`_.
|
||||
|
||||
The idea is to enable dynamic routing when using a service discovery provider so you don't have to provide the ReRoute config. See the docs :ref:`service-discovery` if
|
||||
The idea is to enable dynamic routing when using a service discovery provider so you don't have to provide the Route config. See the docs :ref:`service-discovery` if
|
||||
this sounds interesting to you.
|
||||
|
||||
Query Strings
|
||||
@ -187,7 +187,7 @@ Ocelot allows you to specify a query string as part of the DownstreamPathTemplat
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/api/subscriptions/{subscriptionId}/updates?unitId={unitId}",
|
||||
"UpstreamPathTemplate": "/api/units/{subscriptionId}/{unitId}/updates",
|
||||
@ -214,7 +214,7 @@ Ocelot will also allow you to put query string parameters in the UpstreamPathTem
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/api/units/{subscriptionId}/{unitId}/updates",
|
||||
"UpstreamPathTemplate": "/api/subscriptions/{subscriptionId}/updates?unitId={unitId}",
|
||||
|
||||
@ -4,7 +4,7 @@ Service Discovery
|
||||
=================
|
||||
|
||||
Ocelot allows you to specify a service discovery provider and will use this to find the host and port for the downstream service Ocelot is forwarding a request to. At the moment this is only supported in the
|
||||
GlobalConfiguration section which means the same service discovery provider will be used for all ReRoutes you specify a ServiceName for at ReRoute level.
|
||||
GlobalConfiguration section which means the same service discovery provider will be used for all Routes you specify a ServiceName for at Route level.
|
||||
|
||||
Consul
|
||||
^^^^^^
|
||||
@ -34,9 +34,9 @@ Please note the Scheme option defauls to HTTP. It was added in this `PR <https:/
|
||||
"Type": "Consul"
|
||||
}
|
||||
|
||||
In the future we can add a feature that allows ReRoute specfic configuration.
|
||||
In the future we can add a feature that allows Route specfic configuration.
|
||||
|
||||
In order to tell Ocelot a ReRoute is to use the service discovery provider for its host and port you must add the ServiceName and load balancer you wish to use when making requests downstream. At the moment Ocelot has a RoundRobin and LeastConnection algorithm you can use. If no load balancer is specified Ocelot will not load balance requests.
|
||||
In order to tell Ocelot a Route is to use the service discovery provider for its host and port you must add the ServiceName and load balancer you wish to use when making requests downstream. At the moment Ocelot has a RoundRobin and LeastConnection algorithm you can use. If no load balancer is specified Ocelot will not load balance requests.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -157,16 +157,16 @@ This feature was requested in `issue 340 <https://github.com/ThreeMammals/Ocelot
|
||||
An example of this would be calling Ocelot with a url like https://api.mywebsite.com/product/products. Ocelot will take the first segment of
|
||||
the path which is product and use it as a key to look up the service in Consul. If Consul returns a service Ocelot will request it on whatever host and port comes back from Consul plus the remaining path segments in this case products thus making the downstream call http://hostfromconsul:portfromconsul/products. Ocelot will apprend any query string to the downstream url as normal.
|
||||
|
||||
In order to enable dynamic routing you need to have 0 ReRoutes in your config. At the moment you cannot mix dynamic and configuration ReRoutes. In addition to this you need to specify the Service Discovery provider details as outlined above and the downstream http/https scheme as DownstreamScheme.
|
||||
In order to enable dynamic routing you need to have 0 Routes in your config. At the moment you cannot mix dynamic and configuration Routes. In addition to this you need to specify the Service Discovery provider details as outlined above and the downstream http/https scheme as DownstreamScheme.
|
||||
|
||||
In addition to that you can set RateLimitOptions, QoSOptions, LoadBalancerOptions and HttpHandlerOptions, DownstreamScheme (You might want to call Ocelot on https but talk to private services over http) that will be applied to all of the dynamic ReRoutes.
|
||||
In addition to that you can set RateLimitOptions, QoSOptions, LoadBalancerOptions and HttpHandlerOptions, DownstreamScheme (You might want to call Ocelot on https but talk to private services over http) that will be applied to all of the dynamic Routes.
|
||||
|
||||
The config might look something like
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [],
|
||||
"Routes": [],
|
||||
"Aggregates": [],
|
||||
"GlobalConfiguration": {
|
||||
"RequestIdKey": null,
|
||||
@ -204,12 +204,12 @@ The config might look something like
|
||||
}
|
||||
}
|
||||
|
||||
Ocelot also allows you to set DynamicReRoutes which lets you set rate limiting rules per downstream service. This is useful if you have for example a product and search service and you want to rate limit one more than the other. An example of this would be as follows.
|
||||
Ocelot also allows you to set DynamicRoutes which lets you set rate limiting rules per downstream service. This is useful if you have for example a product and search service and you want to rate limit one more than the other. An example of this would be as follows.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"DynamicReRoutes": [
|
||||
"DynamicRoutes": [
|
||||
{
|
||||
"ServiceName": "product",
|
||||
"RateLimitRule": {
|
||||
@ -239,6 +239,6 @@ Ocelot also allows you to set DynamicReRoutes which lets you set rate limiting r
|
||||
}
|
||||
}
|
||||
|
||||
This configuration means that if you have a request come into Ocelot on /product/* then dynamic routing will kick in and ocelot will use the rate limiting set against the product service in the DynamicReRoutes section.
|
||||
This configuration means that if you have a request come into Ocelot on /product/* then dynamic routing will kick in and ocelot will use the rate limiting set against the product service in the DynamicRoutes section.
|
||||
|
||||
Please take a look through all of the docs to understand these options.
|
||||
|
||||
@ -3,14 +3,14 @@ Service Fabric
|
||||
|
||||
If you have services deployed in Service Fabric you will normally use the naming service to access them.
|
||||
|
||||
The following example shows how to set up a ReRoute that will work in Service Fabric. The most important thing is the ServiceName which is made up of the Service Fabric application name then the specific service name. We also need to set up the ServiceDiscoveryProvider in GlobalConfiguration. The example here shows a typical configuration. It assumes service fabric is running on localhost and that the naming service is on port 19081.
|
||||
The following example shows how to set up a Route that will work in Service Fabric. The most important thing is the ServiceName which is made up of the Service Fabric application name then the specific service name. We also need to set up the ServiceDiscoveryProvider in GlobalConfiguration. The example here shows a typical configuration. It assumes service fabric is running on localhost and that the naming service is on port 19081.
|
||||
|
||||
The example below is taken from the samples folder so please check it if this doesnt make sense!
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/api/values",
|
||||
"UpstreamPathTemplate": "/EquipmentInterfaces",
|
||||
|
||||
@ -1,41 +1,41 @@
|
||||
Tracing
|
||||
=======
|
||||
|
||||
This page details how to perform distributed tracing with Ocelot. At the moment we only support Butterfly but other tracers might just work without
|
||||
anything Ocelot specific.
|
||||
|
||||
Butterfly
|
||||
^^^^^^^^^
|
||||
|
||||
Ocelot providers tracing functionality from the excellent `Butterfly <https://github.com/liuhaoyang/butterfly>`_ project. The code for the Ocelot integration
|
||||
can be found `here <https://github.com/ThreeMammals/Ocelot.Tracing.Butterfly>`_.
|
||||
|
||||
In order to use the tracing please read the Butterfly documentation.
|
||||
|
||||
In ocelot you need to do the following if you wish to trace a ReRoute.
|
||||
|
||||
``Install-Package Ocelot.Tracing.Butterfly``
|
||||
|
||||
In your ConfigureServices method
|
||||
|
||||
.. code-block:: csharp
|
||||
|
||||
services
|
||||
.AddOcelot()
|
||||
// this comes from Ocelot.Tracing.Butterfly package
|
||||
.AddButterfly(option =>
|
||||
{
|
||||
//this is the url that the butterfly collector server is running on...
|
||||
option.CollectorUrl = "http://localhost:9618";
|
||||
option.Service = "Ocelot";
|
||||
});
|
||||
|
||||
Then in your ocelot.json add the following to the ReRoute you want to trace..
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"HttpHandlerOptions": {
|
||||
"UseTracing": true
|
||||
},
|
||||
|
||||
Ocelot will now send tracing information to Butterfly when this ReRoute is called.
|
||||
Tracing
|
||||
=======
|
||||
|
||||
This page details how to perform distributed tracing with Ocelot. At the moment we only support Butterfly but other tracers might just work without
|
||||
anything Ocelot specific.
|
||||
|
||||
Butterfly
|
||||
^^^^^^^^^
|
||||
|
||||
Ocelot providers tracing functionality from the excellent `Butterfly <https://github.com/liuhaoyang/butterfly>`_ project. The code for the Ocelot integration
|
||||
can be found `here <https://github.com/ThreeMammals/Ocelot.Tracing.Butterfly>`_.
|
||||
|
||||
In order to use the tracing please read the Butterfly documentation.
|
||||
|
||||
In ocelot you need to do the following if you wish to trace a Route.
|
||||
|
||||
``Install-Package Ocelot.Tracing.Butterfly``
|
||||
|
||||
In your ConfigureServices method
|
||||
|
||||
.. code-block:: csharp
|
||||
|
||||
services
|
||||
.AddOcelot()
|
||||
// this comes from Ocelot.Tracing.Butterfly package
|
||||
.AddButterfly(option =>
|
||||
{
|
||||
//this is the url that the butterfly collector server is running on...
|
||||
option.CollectorUrl = "http://localhost:9618";
|
||||
option.Service = "Ocelot";
|
||||
});
|
||||
|
||||
Then in your ocelot.json add the following to the Route you want to trace..
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
"HttpHandlerOptions": {
|
||||
"UseTracing": true
|
||||
},
|
||||
|
||||
Ocelot will now send tracing information to Butterfly when this Route is called.
|
||||
|
||||
@ -15,7 +15,7 @@ In your Configure method you need to tell your application to use WebSockets.
|
||||
app.UseOcelot().Wait();
|
||||
})
|
||||
|
||||
Then in your ocelot.json add the following to proxy a ReRoute using websockets.
|
||||
Then in your ocelot.json add the following to proxy a Route using websockets.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
@ -54,12 +54,12 @@ In your Configure method you need to tell your application to use SignalR.
|
||||
app.UseOcelot().Wait();
|
||||
})
|
||||
|
||||
Then in your ocelot.json add the following to proxy a ReRoute using SignalR. Note normal Ocelot routing rules apply the main thing is the scheme which is set to "ws".
|
||||
Then in your ocelot.json add the following to proxy a Route using SignalR. Note normal Ocelot routing rules apply the main thing is the scheme which is set to "ws".
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/{catchAll}",
|
||||
"DownstreamScheme": "ws",
|
||||
@ -84,7 +84,7 @@ Supported
|
||||
2. Routing
|
||||
3. Service Discovery
|
||||
|
||||
This means that you can set up your downstream services running websockets and either have multiple DownstreamHostAndPorts in your ReRoute config or hook your ReRoute into a service discovery provider and then load balance requests...Which I think is pretty cool :)
|
||||
This means that you can set up your downstream services running websockets and either have multiple DownstreamHostAndPorts in your Route config or hook your Route into a service discovery provider and then load balance requests...Which I think is pretty cool :)
|
||||
|
||||
Not Supported
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
@ -22,7 +22,7 @@ The following is a very basic ocelot.json. It won't do anything but should get O
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [],
|
||||
"Routes": [],
|
||||
"GlobalConfiguration": {
|
||||
"BaseUrl": "https://api.mybusiness.com"
|
||||
}
|
||||
@ -33,7 +33,7 @@ If you want some example that actually does something use the following:
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [
|
||||
"Routes": [
|
||||
{
|
||||
"DownstreamPathTemplate": "/todos/{id}",
|
||||
"DownstreamScheme": "https",
|
||||
@ -124,7 +124,7 @@ The following is a very basic ocelot.json. It won't do anything but should get O
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"ReRoutes": [],
|
||||
"Routes": [],
|
||||
"GlobalConfiguration": {}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user