Creating an API Gateway using Ocelot.NET and Consul in ASP.NET Core (.NET 5) with Docker

This tutorial is about setting up an API Gateway using Ocelot.NET and Consul. The consul integration for Ocelot.NET enables you to fetch registered services and load balance between multiple instances.

Prerequisites

• Docker Desktop (for running our services and deploying Consul)
  https://www.docker.com/products/docker-desktop
• IDE of choice, however, I highly recommend Visual Studio because of the simplified docker integration.
• .NET 5 SDK Installed
• Basic knowledge about ASP.NET Core and Docker.

Tutorial Content

1. Deploying Consul using Docker Desktop.
2. Creating a sample API (microservice 1) and registering it with Consul
3. Creating the API Gateway using Ocelot.NET and integrating Consul

Completed Tutorial Source can be found on my GitHub

dominique-k-medium/medium-api-gateway-ocelot-consul

1 Deploying Consul using Docker Desktop

Open your Terminal/Command Prompt

Copy and paste the following command:

docker run -d — name=dev-consul -p 8500:8500 -p 8600:8600 — restart unless-stopped consul

This will deploy Consul locally on your desktop.

Run the following command to check if Consul is running:

docker container list

docker container list — results

2 Creating a sample API and registering it with Consul

Next up is creating a simple API. I’ll be using the default Web API template from Asp.NET Core

I’ve used the following settings while creating the project using Visual Studio

Visual Studio Project Settings

Don’t see these settings in Visual Studio? Try following this guide first

After creating your project, your directory structure should look like this:

Next, we’ll be adding the required NuGet Package and Service for registering our SampleAPI with Consul.

Install the following NuGet package to your project:

Consul 1.6.1.1

Next, add the following class to your project:

ConsulServiceExtension.cs

Next, add the following information to your appsettings.json (located in your project root directory)

Explanation:

• ConsulHost = Consul Http Address. — This should contain your local IP address (How to find my local IP).
• ServiceName = Name of the service.
• ServicePort = Http/Https Port of the service.

Next, add the following lines of code to your Startup.cs file.

In the ConfigureServices Method add:

services.AddHealthChecks();
services.AddConsulConfig(Configuration);

In the Configure Method add:

app.UseConsul(Configuration);

Inside the same Configure method update the app.UseEndpoints call with the following information:

app.UseEndpoints(endpoints =>
{
  endpoints.MapHealthChecks(“/health”);
  endpoints.MapControllers();
});

Next, adding Docker support:

If you’re using Visual Studio, right-click on your project and Click on Add > Add Docker Support

Or manually create a new file called Dockerfile and update the Dockerfile with the following content:

If your project isn’t called SampleAPI, please change the Dockerfile accordingly.

Let’s start our SampleAPI and see if it registers with Consul.

If you’re using Visual Studio you can simply start the application using Docker by selecting Docker as the startup option.

If you’re not using Visual Studio, please check your IDE’s website on how to run Dockerfiles inside your IDE.

Alternatively, you can build and run your docker file manually.
Open a terminal in your root directory and run the following commands:

docker build -t sampleapi .
docker run sampleapi

After running your application using docker go to your Consul page (http://localhost:8500)

Consul showing our SampleAPI

Your SampleAPI should be registered with Consul. Feel free to click on SampleAPI to see some more information about your registered Service.

3 Creating the API Gateway using Ocelot.NET and integrating Consul

Create a new ASP.NET Core project, this time I’ll be using the ASP.NET Core Empty template.

Next, Install the following NuGet packages (Ocelot & Ocelot.Provider.Consul)

Ocelot 17.0.0

Ocelot.Provider.Consul 17.0.0

Next, change your Program.cs file to contain the following information:

Next, create 2 new files called ocelot.development.json and ocelot.producion.json

The JSON file is determined by our environment setting called ASPNETCORE_ENVIRONMENT — by default “development”

Now update your ocelot.development.json with the following content:

Please change the IP Addresses accordingly. ServiceDiscoveryProvider::Host should be your local IP address.

Next, adding Docker support:

If you're using Visual Studio, right-click on your project and Click on Add > Add Docker Support

Or manually create a new file called Dockerfile and update the Dockerfile with the following content:

If your project isn’t called ApiGateway, please change the Dockerfile accordingly.

Let’s start our API gateway.

If you’re using Visual Studio you can simply start the application using Docker by selecting Docker as the startup option.

If you’re not using Visual Studio, please check your IDE’s website on how to run Dockerfiles inside your IDE.

Alternatively, you can build and run your docker file manually.
Open a terminal in your root directory and run the following commands:

docker build -t apigateway.
docker run apigateway -p <HOSTPORT>:80

Visual Studio: Got an SSL Error? Goto launchSettings.json (inside the Properties directory) and set useSSL to false

launchSettings.json Docker section

After starting the API Gateway go to its URL/api/weather and it should display the WeatherForecast information from our SampleAPI.

(in my case http://localhost:49166/api/weather)

which shows the following results:

WeatherForecast results from our API Gateway

Completed Tutorial Source can be found on my GitHub

dominique-k-medium/medium-api-gateway-ocelot-consul

You’ve now successfully created an API Gateway that uses Consul to fetch downstream services.

Thanks for reading.