Skip to content

Commit

Permalink
Rename all ReRoute to Route to move closer to YARP +semver: breaking
Browse files Browse the repository at this point in the history
  • Loading branch information
TomPallister authored May 23, 2020
1 parent fe3e8bd commit 3439be8
Show file tree
Hide file tree
Showing 269 changed files with 23,587 additions and 23,601 deletions.
26 changes: 13 additions & 13 deletions docs/features/authentication.rst
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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",
Expand All @@ -30,17 +30,17 @@ 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",
"AllowedScopes": []
}
}]
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
^^^^^^^^^^
Expand All @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/features/authorisation.rst
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/features/caching.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/features/claimstransformation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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...

Expand Down
16 changes: 8 additions & 8 deletions docs/features/configuration.rst
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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": [
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down
6 changes: 3 additions & 3 deletions docs/features/delegatinghandlers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down
10 changes: 5 additions & 5 deletions docs/features/headerstransformation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -25,15 +25,15 @@ 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
"DownstreamHeaderTransform": {
"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..

Expand All @@ -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
Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions docs/features/kubernetes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand Down
Loading

0 comments on commit 3439be8

Please sign in to comment.