Implementing API Gateways with Ocelot (New section for the Microservices eBook) #5854
Conversation
…net-architecture/docs into features/api-gateways-ocelot
…net-architecture/docs into features/api-gateways-ocelot
There was a problem hiding this comment.
Overall, this is good information @CESARDELATORRE
I left a number of comments relating to style and clarity, and several that will make the localization process smoother.
Let me know if you have any questions.
| ms.author: wiwagn | ||
| ms.date: 06/06/2018 | ||
| --- | ||
| # Implementing API Gateways with Ocelot |
There was a problem hiding this comment.
In the title, H1, and the file name, let's change "implementing" to "implement". It will help a lot with localization.
There was a problem hiding this comment.
But in this case, I don't want to be so prescriptive. Ocelot is just one approach.
If I say "Implement API Gateways with Ocelot" it sounds like we just recommend to do it with Ocelot.
But other approaches like Azure API Management or additional third parties could also apply..
| - Service Fabric cluster, on-premises or in the cloud | ||
| - Service Fabric mesh, as PaaS/Serverless in Azure | ||
|
|
||
| ## Architecting and designing your API Gateways |
There was a problem hiding this comment.
"Architecting and designing" => "Architect and design"
|
|
||
| The following architecture diagram shows how API Gateways are implemented with Ocelot in eShopOnContainers. | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text in the brackets for accessibility (comment applies to all images)
|
|
||
| **Figure 8-27.** eShopOnContainers architecture with API Gateways | ||
|
|
||
| That diagram shows how the whole application is deployed into a single Docker host or development PC with “Docker for Windows” or “Docker for Mac”. However, deploying into any orchestrator would be pretty similar but any container in the diagram could be scaled-out in the orchestrator and the infrastructure assets such as databases, cache, and message brokers should be offloaded from the orchestrator and deployed into high available systems for infrastructure, like Azure SQL Database, Azure Cosmos DB, Azure Redis, Azure Service Bus, or any HA clustering solution on-premises. |
There was a problem hiding this comment.
"HA" should be defined on first use (assume you mean High Availability)
|
|
||
| As you can also notice in the diagram, having several API Gateways allows multiple development teams to be autonomous (in this case Marketing features vs. Shopping features) when developing and deploying their microservices plus their own related API Gateways. If you had a single monolithic API Gateway that would mean a single point to be updated by several development teams, which could couple all the microservices with a single part of the application. | ||
|
|
||
| Going much further in the design, sometimes a fine-grained API Gateway can also be limited to a single business microservice depending on the chosen architecture. Having the API Gateway’s boundaries dictated by the business or domain will help you to get a better design. For instance, fine granularity in the API Gateway tier can be especially useful for more advanced composite UI applications based on microservices, because the concept of a fine-grained API Gateway is similar to a UI composition service. You can read further information about this topic in the section [Creating composite UI based on microservices](https://docs.microsoft.com/dotnet/standard/microservices-architecture/architect-microservice-container-applications/microservice-based-composite-ui-shape-layout). |
There was a problem hiding this comment.
Links inside docs should be relative. (Then the build system finds any issues if we rename or move files later)
|
|
||
| In any case, the authentication module of Ocelot API Gateway will be visited at first when trying to use any secured microservice (if secured at the API Gateway level). That will re-direct to visit the Identity or auth microservice to get the access token so so you can visit the protected services with the access_token. | ||
|
|
||
| The way you secure with authentication any service at the API Gateway level is by setting the AuthenticationProviderKey in its related settings at the configuration.json. |
There was a problem hiding this comment.
code fence AuthentificationProviderey
bold configuration.json
| } | ||
| ``` | ||
|
|
||
| When Ocelot runs, it will look at the 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. |
There was a problem hiding this comment.
If "ReRoutes" represents a type, code fence it. Otherwise, it should be "reroutes".
AuthenticationOptions.AuthenicationProviderKey should be code fenced.
| { | ||
| private readonly IConfiguration _cfg; | ||
|
|
||
| public Startup(IConfiguration configuration) |
There was a problem hiding this comment.
nit: We're trying to promote newer features. This could be:
public Startup(IConfiguration configuration) => _cfg = configuration;| }); | ||
| ``` | ||
|
|
||
| Now, if you try to access any secured microservice like the Basket microservice with a ReRoute URL based on the API Gateway like http://localhost:5202/api/v1/b/basket/1 then you’ll get a 401 Unauthorized unless you provide a valid token. On the other hand, if a ReRoute URL is authenticated, Ocelot will invoke whatever downstream scheme is associated with it (the internal microservice URL). |
There was a problem hiding this comment.
code fence Basket, ReRoute (see previous comment)
bold URL
code fence 401 Unauthorized
| } | ||
| ``` | ||
|
|
||
| In that example, when the authorization middleware is called, Ocelot will find if the user has the claim type “UserType” in the token and if the value of that claim is “employee”. If it isn’t then the user will not be authorized and the response will be 403 forbidden. |
| @@ -0,0 +1,566 @@ | |||
| --- | |||
There was a problem hiding this comment.
remove ing verbs from file name and remove words that don't add SEO value such as articles, with, etc.
so file name could be implement-api-gateways-ocelot
See rules here
There was a problem hiding this comment.
I would like to make an exception for this particular case (Ocelot). In this case, I don't want to be so prescriptive. Ocelot is just one approach.
If I say "Implement API Gateways with Ocelot" it sounds like we just recommend to do it with Ocelot. Don't you think so?
But other approaches like Azure API Management or additional third parties could also apply..
There was a problem hiding this comment.
Gerunds vs imperative is a huge debate on the tech writing world. I'm fine leaving in the title but I'd remove the ing from the file name since it helps with SEO. People usually search for implement API Gateways or How do I implement...?
| @@ -0,0 +1,566 @@ | |||
| --- | |||
| title: Implementing API Gateways with Ocelot | |||
| description: .NET Microservices Architecture for Containerized .NET Applications | Implementing API Gateways with Ocelot, an Open Source lightweight API Gateway based on .NET Core | |||
There was a problem hiding this comment.
Let's start adding proper descriptions. The description is a call to action for someone to visit your page, it should tell the reader what they're going to get from this page.
|
|
||
| In regards the microservice URL, when the containers are deployed in your local development PC (local Docker host), each microservice’s container has always an internal port (usually port 80) specified in its dockerfile, as in the following dockerfile. | ||
|
|
||
| ```csharp |
There was a problem hiding this comment.
using csharp as the identifier for this and the next code block is breaking the formatting
| } | ||
| } | ||
| ``` | ||
| The DownstreamPathTemplate, Scheme and DownstreamHostAndPorts make the internal microservice URL that this request will be forwarded to. |
There was a problem hiding this comment.
add empty line
inline code the API names
| [Route("api/v1/[controller]")] | ||
| [Authorize] | ||
| public class BasketController : Controller | ||
| { //... |
There was a problem hiding this comment.
github doesn't like when the fences are not closed for code blocks. it breaks formatting too
|
|
||
| Therefore, having an ingress Nginx tier in Kuberentes in front of the web applications plus the several Ocelot API Gateways / BFF is the ideal architecture, as shown in the following diagram. | ||
|
|
||
|  |
There was a problem hiding this comment.
images should be put in a directory with the article name inside media
and image names should also use friendly names to help with SEO too
|
Please, merge this PR when possible as it's already been reviewed and updated based on comments. 👍 |
|
@CESARDELATORRE I haven't finished reviewing, but one quick repeated comment: The ``` tags need to be fixed per Maira and my earlier comments. Most of those are using the incorrect language and that causes very bad formatting. In the meantime, I'll continue reviewing. |
| @@ -0,0 +1,566 @@ | |||
| --- | |||
There was a problem hiding this comment.
Gerunds vs imperative is a huge debate on the tech writing world. I'm fine leaving in the title but I'd remove the ing from the file name since it helps with SEO. People usually search for implement API Gateways or How do I implement...?
| @@ -0,0 +1,579 @@ | |||
| --- | |||
| title: Implementing API Gateways with Ocelot | |||
| description: .NET Microservices Architecture for Containerized .NET Applications | In this section you can learn how to implement API Gateways with Ocelot, which is an open sourced and lightweight API Gateway based on .NET Core. You will also learn how to use Ocelot in a container-based environment. | |||
There was a problem hiding this comment.
This is too long. Book title should not be here.
Suggestion: Learn how to implement API Gateways with Ocelot and how to use Ocelot in a container-based environment.
There was a problem hiding this comment.
OK, changed the DESCRIPTION and tags for no C# (like YAML) are now as simply ```
However, I still want to keep "ing" for this specific section as it is not imperative to use Ocelot. Ocelot is just one possible option.
I'll change the filename, as you suggest. :)
|
|
||
| The reference microservice application [eShopOnContainers](https://github.com/dotnet-architecture/eShopOnContainers) is using [Ocelot](https://github.com/ThreeMammals/Ocelot) because Ocelot is a simple and lightweight API Gateway that you can deploy anywhere along with your microservices/containers such as in any of the following environments used by eShopOnContainers. | ||
|
|
||
| - Docker host, in your local dev PC, on-premises or in the cloud |
There was a problem hiding this comment.
replace tabs with a space. add punctuation
|
|
||
| For instance, fine granularity in the API Gateway tier can be especially useful for more advanced composite UI applications that are based on microservices, because the concept of a fine-grained API Gateway is similar to a UI composition service. | ||
|
|
||
| You can read further information about this topic in the section [Creating composite UI based on microservices](https://docs.microsoft.com/dotnet/standard/microservices-architecture/architect-microservice-container-applications/microservice-based-composite-ui-shape-layout). |
There was a problem hiding this comment.
topic -> article
The boilerplate sentence for this situation is "For more information about X, see Y".
We also use relative paths for internal links so we can get links validated at build time.
There was a problem hiding this comment.
👍 -
About the link, I'd prefer to keep the full path so it is consistent with the WORD/PDF version.
|
|
||
| ### Sample microservices/containers to reroute through the API Gateways | ||
|
|
||
| As an example, 'eShopOnContainers' has around six internal microservice-types that have to be published through the API Gateways, as shown in the following image. |
There was a problem hiding this comment.
use backticks instead of single quotes
end with :
| } | ||
| } | ||
| ``` | ||
| The DownstreamPathTemplate, Scheme, and DownstreamHostAndPorts make the internal microservice URL that this request will be forwarded to. |
|
|
||
| The port is the internal port used by the service. When using containers, the port specified at its dockerfile. | ||
|
|
||
| The Host will be a service name that will depend on the service name resolution you are using. When using docker-compose, the services names are provided by the Docker Host, which is using the service names provided in the docker-compose files. If using an orchestrator like Kubernetes or Service Fabric, that name should be resolved by the DNS or name resolution provided by each orchestrator. |
There was a problem hiding this comment.
can you avoid future tense here?
you are -> you're
|
|
||
| At this point, you could have a single Ocelot API Gateway (ASP.NET Core WebHost) using one or [multiple merged configuration.json files](http://ocelot.readthedocs.io/en/latest/features/configuration.html#merging-configuration-files) or you can also store the [configuration in a Consul KV store](http://ocelot.readthedocs.io/en/latest/features/configuration.html#store-configuration-in-consul). | ||
|
|
||
| But as introduced in the architecture and design section, if you really want to have autonomous microservices it might be better to split that single monolithic API Gateway into multiple API Gateways and/or BFF (Backend for Frontend). For that purpose, let’s see how to implement that approach with Docker containers. |
There was a problem hiding this comment.
link to that section?
add comma before it might be
|
|
||
| **Figure 8-39.** Authentication in Ocelot API Gateway | ||
|
|
||
| Since in eShopOnContainers we have split the API Gateway into multiple BFF (Backend for Frontend) and business areas API Gateways, another option would had been to create an additional API Gateway for cross-cutting concerns. That choice would be fair in a more complex microservice based architecture with multiple cross-cutting concerns microservices. But sin we have just one cross-cutting concerns in eShopOnContainers it was decided to just handle the security service out of the API Gateway realm, for simplicity’s sake. |
There was a problem hiding this comment.
remove we from the text
But sin -> But since?
one cross-cutting concerns ->one cross-cutting concern
add comma before it was decided
Suggestion for the last sentence:
Since there's only one cross-cutting concern in eShopOnContainers, ...
|
|
||
| Since in eShopOnContainers we have split the API Gateway into multiple BFF (Backend for Frontend) and business areas API Gateways, another option would had been to create an additional API Gateway for cross-cutting concerns. That choice would be fair in a more complex microservice based architecture with multiple cross-cutting concerns microservices. But sin we have just one cross-cutting concerns in eShopOnContainers it was decided to just handle the security service out of the API Gateway realm, for simplicity’s sake. | ||
|
|
||
| In any case, the authentication module of Ocelot API Gateway will be visited at first when trying to use any secured microservice (if secured at the API Gateway level). That will redirect to visit the Identity or auth microservice to get the access token so you can access the protected services with the access_token. |
There was a problem hiding this comment.
of Ocelot -> of the Ocelot
should the sentence in parentheses be outside and introducing the sentence perhaps?
can you remove future tense?
|
I've reviewed all comments from Maira and updated accordingly. |
3 participants
Summary
New section - Implementing API Gateways with Ocelot
Includes a new .md plus new images and the references to that .md