tk/Ocelot
1
0
Fork 0
mirror of https://github.com/nsnail/Ocelot.git synced 2025-06-19 12:58:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

Feature/docs (#165)

Browse Source 
* initial readthedocs commit

* docs moved to sphinx / rst / read the docs
This commit is contained in:
Tom Pallister
2017-11-25 15:03:50 +00:00
committed by GitHub
parent 48b5a32676
commit 923276651d
29 changed files with 1973 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/features/administration.rst Normal file
View File

@ -0,0 +1,95 @@
Administration
==============
Ocelot supports changing configuration during runtime via an authenticated HTTP API. The API is authenticated
using bearer tokens that you request from Ocelot iteself. This is provided by the amazing
`Identity Server <https://github.com/IdentityServer/IdentityServer4>`_ project that I have been using for a few years now. Check them out.
In order to enable the administration section you need to do a few things. First of all add this to your
initial configuration.json. The value can be anything you want and it is obviously reccomended don't use
a url you would like to route through with Ocelot as this will not work. The administration uses the
MapWhen functionality of asp.net core and all requests to {root}/administration will be sent there not
to the Ocelot middleware.
.. code-block:: json
"GlobalConfiguration": {
"AdministrationPath": "/administration"
}
This will get the admin area set up but not the authentication.
Please note that this is a very basic approach to
this problem and if needed we can obviously improve on this!
You need to set 3 environmental variables.
``OCELOT_USERNAME``
This need to be the admin username you want to use with Ocelot.
``OCELOT_HASH``
``OCELOT_SALT``
The hash and salt of the password you want to use given hashing algorythm. When requesting bearer tokens for use with the administration api you will need to supply username and password. In order to create a hash and salt of your password please check out HashCreationTests.should_create_hash_and_salt() this technique is based on [this](https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/consumer-apis/password-hashing)
using SHA256 rather than SHA1.
Now if you went with the configuration options above and want to access the API you can use the postman scripts
called ocelot.postman_collection.json in the solution to change the Ocelot configuration. Obviously these
will need to be changed if you are running Ocelot on a different url to http://localhost:5000.
The scripts show you how to request a bearer token from ocelot and then use it to GET the existing configuration and POST
a configuration.
Administration running multiple Ocelot's
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are running multiple Ocelot's in a cluster then you need to use a certificate to sign the bearer tokens used to access the administration API.
In order to do this you need to add two more environmental variables for each Ocelot in the cluster.
``OCELOT_CERTIFICATE``
The path to a certificate that can be used to sign the tokens. The certificate needs to be of the type X509 and obviously Ocelot needs to be able to access it.
``OCELOT_CERTIFICATE_PASSWORD``
The password for the certificate.
Normally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. If all the other Ocelots in the cluster have the same certificate then you are good!
Administration API
^^^^^^^^^^^^^^^^^^
**POST {adminPath}/connect/token**
This gets a token for use with the admin area using the username and password we talk about setting above. Under the hood this calls into an IdentityServer hosted within Ocelot.
The body of the request is form-data as follows
``client_id`` set as admin
``client_secret`` set as secret
``scope`` set as admin
``username`` set as whatever you used
``password`` set aswhatever you used
``grant_type`` set as password
**GET {adminPath}/configuration**
This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.
**POST {adminPath}/configuration**
This overrwrites the existing configuration (should probably be a put!). I reccomend getting your config from the GET endpoint, making any changes and posting it back...simples.
The body of the request is JSON and it is the same format as the FileConfiguration.cs that we use to set up
Ocelot on a file system.
**DELETE {adminPath}/outputcache/{region}**
This clears a region of the cache. If you are using a backplane it will clear all instances of the cache! Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time / just use a distributed cache.
The region is whatever you set against the Region field in the FileCacheOptions section of the Ocelot configuration.

42
docs/features/authentication.rst Normal file
View File

@ -0,0 +1,42 @@
Authentication
==============
Users register authentication services in their Startup.cs as usual but they provide a scheme (key) with each registration e.g.
.. code-block:: csharp
public void ConfigureServices(IServiceCollection services)
{
services.AddAuthentication()
.AddJwtBearer("TestKey", x =>
{
x.Authority = "test";
x.Audience = "test";
});
services.AddOcelot(Configuration);
}
In this example TestKey is the scheme tha this provider has been registered with.
We then map this to a ReRoute in the configuration e.g.
.. code-block:: json
"ReRoutes": [{
"DownstreamPathTemplate": "/",
"UpstreamPathTemplate": "/",
"UpstreamHttpMethod": ["Post"],
"ReRouteIsCaseSensitive": false,
"DownstreamScheme": "http",
"DownstreamHost": "localhost",
"DownstreamPort": 51876,
"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.

18
docs/features/authorisation.rst Normal file
View File

@ -0,0 +1,18 @@
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.
.. code-block:: json
"RouteClaimsRequirement": {
"UserType": "registered"
}
In this example when the authorisation middleware is called Ocelot will check to see
if the user has the claim type UserType and if the value of that claim is registered.
If it isn't then the user will not be authorised and the response will be 403 forbidden.

21
docs/features/caching.rst Normal file
View File

@ -0,0 +1,21 @@
Caching
=======
Ocelot supports some very rudimentary caching at the moment provider by
the `CacheManager <http://cachemanager.net/>`_ project. This is an amazing project
that is solving a lot of caching problems. I would reccomend using this package to
cache with Ocelot. If you look at the example `here <https://github.com/TomPallister/Ocelot/blob/develop/test/Ocelot.ManualTest/Startup.cs>`_ you can see how the cache manager is setup and then passed into the Ocelot
AddOcelotOutputCaching configuration method. You can use any settings supported by
the CacheManager package and just pass them in.
Anyway Ocelot currently supports caching on the URL of the downstream service
and setting a TTL in seconds to expire the cache. You can also clear the cache for a region
by calling Ocelot's administration API.
In order to use caching on a route in your ReRoute configuration add this setting.
.. code-block:: json
"FileCacheOptions": { "TtlSeconds": 15, "Region": "somename" }
In this example ttl seconds is set to 15 which means the cache will expire after 15 seconds.

72
docs/features/claimstransformation.rst Normal file
View File

@ -0,0 +1,72 @@
Claims Transformation
=====================
Ocelot allows the user to access claims and transform them into headers, query string
parameters and other claims. This is only available once a user has been authenticated.
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 and Finally
the claims to query strig parameters middleware.
The syntax for performing the transforms is the same for each proces. In the ReRoute
configuration a json dictionary is added with a specific name either AddClaimsToRequest,
AddHeadersToRequest, AddQueriesToRequest.
Note I'm not a hotshot programmer so have no idea if this syntax is good..
Within this dictionary the entries specify how Ocelot should transform things!
The key to the dictionary is going to become the key of either a claim, header
or query parameter.
The value of the entry is parsed to logic that will perform the transform. First of
all a dictionary accessor is specified e.g. Claims[CustomerId]. This means we want
to access the claims and get the CustomerId claim type. Next is a greater than (>)
symbol which is just used to split the string. The next entry is either value or value with
and indexer. If value is specifed Ocelot will just take the value and add it to the
transform. If the value has an indexer Ocelot will look for a delimiter which is provided
after another greater than symbol. Ocelot will then split the value on the delimiter
and add whatever was at the index requested to the transform.
Claims to Claims Tranformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Below is an example configuration that will transforms claims to claims
.. code-block:: json
"AddClaimsToRequest": {
"UserType": "Claims[sub] > value[0] > |",
"UserId": "Claims[sub] > value[1] > |"
}
This shows a transforms where Ocelot looks at the users sub claim and transforms it into
UserType and UserId claims. Assuming the sub looks like this "usertypevalue|useridvalue".
Claims to Headers Tranformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Below is an example configuration that will transforms claims to headers
.. code-block:: json
"AddHeadersToRequest": {
"CustomerId": "Claims[sub] > value[1] > |"
}
This shows a transform where Ocelot looks at the users sub claim and trasnforms it into a
CustomerId header. Assuming the sub looks like this "usertypevalue|useridvalue".
Claims to Query String Parameters Tranformation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Below is an example configuration that will transforms claims to query string parameters
.. code-block:: json
"AddQueriesToRequest": {
"LocationId": "Claims[LocationId] > value",
}
This shows a transform where Ocelot looks at the users LocationId claim and add its as
a query string parameter to be forwarded onto the downstream service.

102
docs/features/configuration.rst Normal file
View File

@ -0,0 +1,102 @@
Configuration
============
An example configuration can be found `here <https://github.com/TomPallister/Ocelot/blob/develop/test/Ocelot.ManualTest/configuration.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.
.. code-block:: json
{
"ReRoutes": [],
"GlobalConfiguration": {}
}
Follow Redirects / Use CookieContainer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use HttpHandlerOptions in ReRoute configuration to set up HttpHandler behavior:
- _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 true.
- _UseCookieContainer_ is a value that indicates whether the handler uses the CookieContainer property to store server cookies and uses these cookies when sending requests.
The default value is true.
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:
.. code-block:: json
{
"DownstreamPathTemplate": "/",
"UpstreamPathTemplate": "/",
"UpstreamHttpMethod": [
"Get"
],
"AddHeadersToRequest": {},
"AddClaimsToRequest": {},
"RouteClaimsRequirement": {},
"AddQueriesToRequest": {},
"RequestIdKey": "",
"FileCacheOptions": {
"TtlSeconds": 0,
"Region": ""
},
"ReRouteIsCaseSensitive": false,
"ServiceName": "",
"DownstreamScheme": "http",
"DownstreamHost": "localhost",
"DownstreamPort": 51779,
"QoSOptions": {
"ExceptionsAllowedBeforeBreaking": 0,
"DurationOfBreak": 0,
"TimeoutValue": 0
},
"LoadBalancer": "",
"RateLimitOptions": {
"ClientWhitelist": [],
"EnableRateLimiting": false,
"Period": "",
"PeriodTimespan": 0,
"Limit": 0
},
"AuthenticationOptions": {
"AuthenticationProviderKey": "",
"AllowedScopes": []
},
"HttpHandlerOptions": {
"AllowAutoRedirect": true,
"UseCookieContainer": true
},
"UseServiceDiscovery": false
}
More information on how to use these options is below..
Store configuration in consul
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you add the following when you register your services Ocelot will attempt to store and retrieve its configuration in consul KV store.
.. code-block:: csharp
services
.AddOcelot(Configuration)
.AddStoreOcelotConfigurationInConsul();
You also need to add the following to your configuration.json. This is how Ocelot
finds your Consul agent and interacts to load and store the configuration from Consul.
.. code-block:: json
"GlobalConfiguration": {
"ServiceDiscoveryProvider": {
"Host": "localhost",
"Port": 9500
}
}
I decided to create this feature after working on the raft consensus algorithm and finding out its super hard. Why not take advantage of the fact Consul already gives you this!
I guess it means if you want to use Ocelot to its fullest you take on Consul as a dependency for now.
This feature has a 3 second ttl cache before making a new request to your local consul agent.

14
docs/features/logging.rst Normal file
View File

@ -0,0 +1,14 @@
Logging
=======
Ocelot uses the standard logging interfaces ILoggerFactory / ILogger<T> at the moment.
This is encapsulated in IOcelotLogger / IOcelotLoggerFactory with an implementation
for the standard asp.net core logging stuff at the moment.
There are a bunch of debugging logs in the ocelot middlewares however I think the
system probably needs more logging in the code it calls into. Other than the debugging
there is a global error handler that should catch any errors thrown and log them as errors.
The reason for not just using bog standard framework logging is that I could not
work out how to override the request id that get's logged when setting IncludeScopes
to true for logging settings. Nicely onto the next feature.

41
docs/features/middlewareinjection.rst Normal file
View File

@ -0,0 +1,41 @@
Middleware Injection and Overrides
==================================
Warning use with caution. If you are seeing any exceptions or strange behavior in your middleware
pipeline and you are using any of the following. Remove them and try again!
When setting up Ocelot in your Startup.cs you can provide some additonal middleware
and override middleware. This is done as follos.
.. code-block:: csharp
var configuration = new OcelotMiddlewareConfiguration
{
PreErrorResponderMiddleware = async (ctx, next) =>
{
await next.Invoke();
}
};
app.UseOcelot(configuration);
In the example above the provided function will run before the first piece of Ocelot middleware.
This allows a user to supply any behaviours they want before and after the Ocelot pipeline has run.
This means you can break everything so use at your own pleasure!
The user can set functions against the following.
* PreErrorResponderMiddleware - Already explained above.
* PreAuthenticationMiddleware - This allows the user to run pre authentication logic and then call Ocelot's authentication middleware.
* AuthenticationMiddleware - This overrides Ocelots authentication middleware.
* PreAuthorisationMiddleware - This allows the user to run pre authorisation logic and then call Ocelot's authorisation middleware.
* AuthorisationMiddleware - This overrides Ocelots authorisation middleware.
* PreQueryStringBuilderMiddleware - This alows the user to manipulate the query string on the http request before it is passed to Ocelots request creator.
Obviously you can just add middleware as normal before the call to app.UseOcelot() It cannot be added
after as Ocelot does not call the next middleware.

22
docs/features/qualityofservice.rst Normal file
View File

@ -0,0 +1,22 @@
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 the an awesome
.NET library called Polly check them out `here <https://github.com/App-vNext/Polly>`_.
Add the following section to a ReRoute configuration.
.. code-block:: json
"QoSOptions": {
"ExceptionsAllowedBeforeBreaking":3,
"DurationOfBreak":5,
"TimeoutValue":5000
}
You must set a number greater than 0 against ExceptionsAllowedBeforeBreaking for this rule to be
implemented. Duration of break is how long the circuit breaker will stay open for after it is tripped.
TimeoutValue means ff a request takes more than 5 seconds it will automatically be timed out.
If you do not add a QoS section QoS will not be used.

28
docs/features/requestid.rst Normal file
View File

@ -0,0 +1,28 @@
Request Id / Correlation Id
===========================
Ocelot supports a client sending a request id in the form of a header. If set Ocelot will
use the requestid for logging as soon as it becomes available in the middleware pipeline.
Ocelot will also forward the request id with the specified header to the downstream service.
I'm not sure if have this spot on yet in terms of the pipeline order becasue there are a few logs
that don't get the users request id at the moment and ocelot just logs not set for request id
which sucks. You can still get the framework request id in the logs if you set
IncludeScopes true in your logging config. This can then be used to match up later logs that do
have an OcelotRequestId.
In order to use the requestid feature in your ReRoute configuration add this setting
.. code-block:: json
"RequestIdKey": "OcRequestId"
In this example OcRequestId is the request header that contains the clients request id.
There is also a setting in the GlobalConfiguration section which will override whatever has been
set at ReRoute level for the request id. The setting is as fllows.
.. code-block:: json
"RequestIdKey": "OcRequestId"
It behaves in exactly the same way as the ReRoute level RequestIdKey settings.

67
docs/features/routing.rst Normal file
View File

@ -0,0 +1,67 @@
Routing
=======
Ocelot's primary functionality is to take incomeing http requests and forward them on
to a downstream service. At the moment in the form of another http request (in the future
this could be any transport mechanism.).
Ocelot always adds a trailing slash to an UpstreamPathTemplate.
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.
.. code-block:: json
{
"ReRoutes": [
]
}
In order to set up a ReRoute you need to add one to the json array called ReRoutes like
the following.
.. code-block:: json
{
"DownstreamPathTemplate": "/api/posts/{postId}",
"DownstreamScheme": "https",
"DownstreamPort": 80,
"DownstreamHost" "localhost",
"UpstreamPathTemplate": "/posts/{postId}",
"UpstreamHttpMethod": [ "Put", "Delete" ]
}
The DownstreamPathTemplate, Scheme, Port and Host make the URL that this request will be forwarded to.
The UpstreamPathTemplate is the URL that Ocelot will use to identity which
DownstreamPathTemplate to use for a given request. Finally the UpstreamHttpMethod is used so
Ocelot can distinguish between requests to the same URL and is obviously needed to work :)
You can set a specific list of HTTP Methods or set an empty list to allow any of them. In Ocelot you can add placeholders for variables to your Templates in the form of {something}.
The placeholder needs to be in both the DownstreamPathTemplate and UpstreamPathTemplate. If it is
Ocelot will attempt to replace the placeholder with the correct variable value from the
Upstream URL when the request comes in.
You can also do a catch all type of ReRoute e.g.
.. code-block:: json
{
"DownstreamPathTemplate": "/api/{everything}",
"DownstreamScheme": "https",
"DownstreamPort": 80,
"DownstreamHost" "localhost",
"UpstreamPathTemplate": "/{everything}",
"UpstreamHttpMethod": [ "Get", "Post" ]
}
This will forward any path + query string combinations to the downstream service after the path /api.
At the moment without any configuration Ocelot will default to all ReRoutes being case insensitive.
In order to change this you can specify on a per ReRoute basis the following setting.
.. code-block:: json
"ReRouteIsCaseSensitive": true
This means that when Ocelot tries to match the incoming upstream url with an upstream template the
evaluation will be case sensitive. This setting defaults to false so only set it if you want
the ReRoute to be case sensitive is my advice!

39
docs/features/servicediscovery.rst Normal file
View File

@ -0,0 +1,39 @@
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.
At the moment the only supported service discovery provider is Consul. The following is required in the
GlobalConfiguration. The Provider is required and if you do not specify a host and port the Consul default
will be used.
.. code-block:: json
"ServiceDiscoveryProvider": {
"Host": "localhost",
"Port": 9500
}
In the future we can add a feature that allows ReRoute 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, UseServiceDiscovery 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
{
"DownstreamPathTemplate": "/api/posts/{postId}",
"DownstreamScheme": "https",
"UpstreamPathTemplate": "/posts/{postId}",
"UpstreamHttpMethod": [ "Put" ],
"ServiceName": "product",
"LoadBalancer": "LeastConnection",
"UseServiceDiscovery": false
}
When this is set up Ocelot will lookup the downstream host and port from the service discover provider and load balance
requests across any available services.