This repo contains a sample application that demonstrates the integration of Dapr and Azure API Management (APIM).
APIM has been a PaaS service that was only available on Azure for quite some time. But recently, a new feature was added: the ability to run a self-hosted APIM gateway anywhere you want. This self-hosted gateway needs to connect to an APIM instance in Azure for it to function. This is because all the configuration and monitoring of the APIs that are exposed through the gateway is done in APIM.
The Dapr team has worked on integration of Dapr and the APIM self-hosted gateway. This enables you to run the gateway with a Dapr sidecar and make use of the Dapr building blocks: service invocation, pub/sub and bindings.
The sample application makes use of this feature. The APIM gateway is deployed in a Kubernetes cluster together with a backend service. Both will be deployed with a Dapr sidecar. The backend service will be invoked by the APIM gateway using Dapr building-blocks. The application's architecture is shown in Figure 1:
Figure 1: Application architecture
In API management, there is 1 API defined: eShopAPI
. This API has 2 operations:
-
/addcustomer
: this operation invokes theAddCustomer
method on theCustomerController
of theCustomerService
using the Dapr service invocation building-block. -
/customercreated
: this operation publishes a message on thecustomer-events
topic using the Dapr pub/sub building-block. TheCustomerCreated
method on theCustomerController
of theCustomerService
is subscribed to this topic and will be invoked when a message is sent to the topic. The pub/sub building-block uses the Redis server as message-broker component.
The application is kept as simple as possible in order to focus on the APIM and Dapr concepts. The next paragraphs contain instructions on how to run and test it. Once you have everything up and running, you can start experimenting with adding more functionality. You could for instance add an operation that uses an output-binding to store a customer in the Redis server.
- A Kubernetes cluster (the application was created using Docker Desktop with Kubernetes enabled)
- Kubernetes CLI (kubectl)
- Helm
- Access to an Azure subscription
- VS Code
- .NET 5 SDK
Follow the instructions below to deploy, run and test the application.
The first couple of steps setup the API in APIM. These are one-time initialization steps. Once you have executed them, you can start at Prepare for deployment in Kubernetes.
- Create an Azure API Management instance in your Azure subscription.
-
Make a copy the file
src/apim-setup/env-sample.json
and name itenv.json
. -
Get the
subscription id
of your subscription, the name of theresource group
in which you have created the API Management instance and the name of the API Management instance. Replace the placeholders for these values in theenv.json
file with the actual values. -
Open a Powershell window and go to the folder
src/apim-setup
. -
Run the script
setup-env.ps1
. This script will create an authentication token for calling the APIM management API.
-
Open a Powershell window and go to the folder
src/apim-setup
. -
Run the script
import-api.ps1
. This script wil create the API definition in the APIM instance. See the filesrc/apim-setup/eshop-api.yaml
to inspect the definition. It is in Open API format. -
Run the script
import-global.ps1
. This script will add a rate-limiting policy for all the operations. See the filesrc/apim-setup/policies/global.json
to inspect the policy. -
Run the script
import-addcustomer.ps1
. This script will add theaddcustomer
operation to the API. See the filesrc/apim-setup/policies/addcustomer.json
to inspect the policy. -
Run the script
import-customercreated.ps1
. This script will add thecustomercreated
operation to the API. See the filesrc/apim-setup/policies/customercreated.json
to inspect the policy.
- Run the script
setup-gateway.ps1
. This script will create the APIM gateway (namedeshop-apim-gateway
) and link this to theeShopAPI
API.
-
Open a Powershell window.
-
If you are revisiting the sample after some time, the APIM Management API token probably has expired. In that case, go to the folder
src/apim-setup
and run the scriptsetup-env.ps1
to generate a new token. -
Make sure you have a Kubernetes cluster running in which you can deploy the application. Also make sure the Kubernetes CLI (kubectl) is available.
-
Go to the folder
src/deploy
. -
Run the script
create-namespace.ps1
to create the namespacedapr-apim-sample
in the Kubernetes cluster. -
Run the script
install-redis.ps1
to install a Redis server into the namespace. -
Run the script
create-gateway-configmap.ps1
. This script will create a config-map containing the URI of the API in APIM. This config-setting is used by the gateway to connect to the APIM instance in Azure. -
Run the script
create-gateway-key-secret.ps1
. This script will generate a token for communicating with the APIM gateway in Azure. This token is stored in a Kubernetes secret that will be used by the gateway. The script will generate a token that is valid for 2 days. After token has expired, you can rerun the script to generate a new token.
-
Open a Powershell window and go to the
/src/CustomerService
folder. -
Build the CustomerService docker image by executing the build-docker-image.ps1 script.
-
Go to the folder
src/deploy
. -
Run the script
start.ps1
. This script will create the following resources in the Kubernetes cluster:- A Dapr configuration used by all the sidecars
- A pub/sub component that used the Redis server
- The APIM Gateway
- The
CustomerService
backend service.
-
Install the REST Client extension for VS Code.
-
Create file
.vscode/settings.json
with the following content:{ "rest-client.environmentVariables": { "local": { "AZ_API_SUB_KEY": "<subscripton key>" } } }
-
Run the script
get-api-subscription-key.ps1
. CAUTION: this script will retrieve the subscription-key for your API and show it on the console! Once you see the key, copy it and paste it in thesetting.json
file you've created in the previous step. The settings file will not be pushed to GitHub. -
Open the file
src/requests/customerservice.http
. -
Make sure you select the
local
environment for the REST Client. This is necessary so the API subscription key variable can be read from thesettings.json
file. You can select an environment by clicking on the environment selector in the bottom right of the VS Code status-bar (or use the Ctrl-Alt-E shortcut-key). It probably readsNo Environment
: -
Test the application by invoking the requests. You should receive a
200 OK
when executing theaddcustomer
operation. Thecustomercreated
operation will yield a204 No Content
. -
You can inspect the logging of the
CustomerService
container to see that the service is actually being called.
-
Open a Powershell window and go to the folder
src/deploy
. -
Run the script
stop.ps1
. This script will remove the application resources from the Kubernetes cluster.
If you want to remove everything from the cluster, run the script
src/deploy/delete-all.ps1
. This will remove thedapr-apim-sample
namespace and everything in it (including the configmap, secret and Redis server). The next time you need to restart at Prepare for deployment in Kubernetes.