While working on the Reddog Microservices Integration Application Sample, our objective was to demonstrate a development scenario that uses Bicep to integrate Azure API Management with Azure Container Apps.
DISCLAIMER: This project is not my original work. The repository leverages the Reddog codebase and the Reddog Container Apps bicep modules generously contributed by the Cloud Native Global Black Belt Team. I do not own any rights to the project an do not take credit for any of the amazing design work done by the team.
Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy Azure resources.
Azure API Management is a managed service that allows you to manage services across hybrid and multi-cloud environments. API management acts as a facade to abstract the backend architecture, and it provides control and security for API observability and consumption for both internal and external users.
Azure Container Apps is a fully managed, serverless container service used to build and deploy modern apps at scale. In this solution, you’re hosting microservices on Azure Container Apps and deploying them into a single Container App environment. This environment acts as a secure boundary around the system.
Creating the APIM resource
The first step was to create the main APIM Service resource:
|
|
This will deploy a APIM instance. Of particular note here is virtualNetworkType
declaration. This represents the type of VPN in which API Management service needs to be configured in:
- None (Default Value) means the API Management service is not part of any Virtual Network,
- External means the API Management deployment is set up inside a Virtual Network having an Internet Facing Endpoint, and
- Internal means that API Management deployment is setup inside a Virtual Network having an Intranet Facing Endpoint only.
NOTE: Please bear in mind that APIM takes more than an hour to provision.
Applying a global policy
Next step, we created a global policy definition file apimPolicies/global.xml
:
|
|
Then add the policy resource to the Bicep module:
|
|
The Policy Contract here is defined in xml format, and of particular note here is the loadTextContent function which loads the content of a specified file as a string.
Adding a Backend API
A backend (or API backend) in API Management is an HTTP service that implements your front-end API and its operations. Sometimes backend APIs are referred to simply as backends. API Management supports using other Azure resources as an API backend, such as Container Apps. A custom backend has several benefits, including:
- Abstracts information about the backend service, promoting reusability across APIs and improved governance.
- Easily used by configuring a transformation policy on an existing API.
- Takes advantage of API Management functionality to maintain secrets in Azure Key Vault if named values are configured for header or query parameter authentication.
To create a Microsoft.ApiManagement/service/backends resource, we added the following Bicep to our template.
|
|
Here we reference an existing Container App in our backend resource and use the ingress URL as the backend URL. The resourceId
needs to be a URL for the deployment to work. Here we use the environment()
function, returns properties for the current Azure environment, to get the management URL instead of hard-coding "https://management.azure.com/"
.
Adding a Fronted API
API Management serves as mediation layer over the backend APIs. Frontend API is an API that is exposed to API consumers from API Management. You can customize the shape and behavior of a frontend API in API Management without making changes to the backend API(s) that it represents. Sometimes frontend APIs are referred to simply as APIs.
To create a Microsoft.ApiManagement/service/apis resource, we added the following Bicep to our template.
|
|
subscriptionRequired
: Specifies whether an API or Product subscription is required for accessing the API.path
: Relative URL uniquely identifying this API and all of its resource paths within the API Management service instance. It is appended to the API endpoint base URL specified during the service instance creation to form a public URL for this API.
Adding a Fronted API Policy
A policy is a reusable and composable component, implementing some commonly used API-related functionality. API Management offers over 50 built-in policies that take care of critical but undifferentiated horizontal concerns - for example, request transformation, routing, security, protection, caching. The policies can be applied at various scopes, which determine the affected APIs or operations and dynamically configured using policy expressions. For more information, see Policies in Azure API Management.
In order to make the Fronted API policy reusable, we saved it in a XML file apimPolicies/api.xml
:
|
|
This policy does one thing: Use the set-backend-service
policy to redirect an incoming request to the specified backend for all operations in this Frontend API. For more information, see Set backend service.
In this case, backend-id
is the Identifier (name) of the backend to route requests to, and since we are going to reuse this xml, we will add the {backendName}
token to be replaced later.
To create a Microsoft.ApiManagement/service/apis/policies resource, we then added the following Bicep to our template:
|
|
Here we are basically leveraging a combination of the replace
function and the loadTextContent
function to read the XML file and replace the {backendName}
token with the actual Backend API we want to route requests to.
Adding a Fronted API Operation
A frontend API in API Management can define multiple operations. An operation is a combination of an HTTP verb and a URL template uniquely resolvable within the frontend API. Often operations map one-to-one to backend API endpoints. For more information, see Mock API responses.
To create a Microsoft.ApiManagement/service/apis/operations resource, we added the following Bicep to our template:
|
|
Adding a Operation policy
In order to make the Operation policy reusable, we saved it in a XML file apimPolicies/operation.xml
:
|
|
This policy does three things:
set-method
: sets the HTTP request method for a request. See Set request methodrewrite-url
: converts a request URL from its public form to the form expected by the web service. See Rewrite URLset-header
: assigns a value to an existing response and/or request header or adds/removes a new response and/or request header. See Set HTTP header
Repeat
Steps 3 - 7 are repeated for all Backend APIs, Frontend APIs, Policies, and operations that need to be defined on Azure API Management.
Hope this proves valuable to you, dear reader.
Credits:
RedDog Codebase
RedDog Container Apps
Cloud Native Global Black Belt Team
References:
Bicep
Azure API Management
Azure Container Apps
Azure API Management terminology
Bicep functions
API Management policy reference
Define resources with Bicep, ARM templates, and Terraform AzAPI provider