This blog helps to set up the Azure API Management-devops-resource-kit , gives details on how to run the creator and extractor tools to generate ARM templates and lists out common questions and answers.
The generated ARM templates using APIM DevOps toolkit can further be integrated with DevOps tool for automated deployment in different environments.
Understanding DevOps
- It is a group of procedures, equipment, and cultural ideals that integrate and automate the procedures between IT and software development teams.
- It increases the effectiveness, speed, and security of software development and delivery compared to conventional approaches by combining development and operations.
- DevOps Life Cycle contains phases shown in below diagram:
DevOps tools
- DevOps Tool is an application that helps automate the software development process. It mainly focuses on communication and collaboration between product management, software development, and operations professionals.
- enables teams to automate most of the software development processes like build, conflict management, dependency management, deployment, etc. and helps reduce manual efforts.
- Example of tools - Azure devops, Jenkins, Ansible, Puppet
azure-api-management-devops-resource-kit
- Contains Creator and extractor tools with samples.
- These tools help us to create ARM templates which can be integrated in dev-ops pipeline.
- The deployment of the templates can be automated using Github Actions, Azure Pipeline, PowerShell, Azure CLI or other tools.
- To start using this kit, we need to download its code.
Code Set-up
- Get the code from https://github.com/Azure/azure-api-management-devops-resource-kit
- Downloaded code:
- Next step is to open code folder in Visual Studio code as shown below:
- Restore packages using dotnet restore command in Terminal.
- ArmTemplates folder contain “Creator” and “Extractor” tools:
- Example folder contains pre-created files which we can use to understand the functioning of azure-api-management-devops-resource-kit
Creator tool
This utility creates Resource Manager templates for an API based on the OpenAPI Specification of the API. Optionally, you can provide policies you wish to apply to the API and its operations in separate files.
Create the config file using the configuration settings given in: https://github.com/Azure/azure-api-management-devops-resource-kit/blob/main/src/README.md#Creator
Common Scenario:
Let’s say we have OpenAPI specification (swagger file) and we want to generate APIM ARM template out of it which will help us in creating APIM in subsequent environments like staging, PROD.
Solution:
- In this scenario we must use creator tool to generate ARM templates.
- To get an understanding of Creator, we will use default file provided as below:
- Here Valid.yml is the Creator tool’s Configuration file.
- This file states apimServiceName, apiVersionSets, apis and outputlocation settings.
- Creator tool will create ARM template using these settings and will place the generated files in the folder mentioned in outputlocation settings.
- We can run creator tool using below command:
- dotnet run create --configFile CONFIG_YAML_FILE_LOCATION
- We will use Valid.yml which is already provided in the solution, and it’s customized as per requirement.
- We will use swaggerPetstore.json which is the OpenAPI specification file which is already provided in the solution.
- Open command prompt and navigate to the ARMTemplates folder location and run below command. (Path will change)
- dotnet run create --configFile C:\Aditi\DevOps\azure-api-management-devops-resource-kit-main\azure-api-management-devops-resource-kit-main\example\demo\Input\valid.yml
- After running creator command, tool creates ARM templates and places them in the location mentioned in the valid.yml file.
For more details on creator tool, settings etc. Please refer https://github.com/Azure/azure-api-management-devops-resource-kit/blob/main/src/README.md#Creator
Extractor tool
This utility generates Resource Manager templates by extracting existing configurations of one or more APIs in an API Management instance.
To run extractor commands we need to get Azure CLI installed first.
Example Scenario:
APIM is already created on Azure, and we want to extract ARM template out of it for deployments in subsequent environments.
- Existing APIM
- Create extractor settings file. Example – extractorSettings.json
- Open command prompt and navigate to the ARMTemplates folder location and run below command. (Path will change)
- “dotnet run extract --extractorConfig C:\Aditi\DevOps\azure-api-management-devops-resource-kit-main\azure-api-management-devops-resource-kit-main\example\ExtratorSample_Aditi\extractorSetting.json”
- Output:
For more details on Extractor commands, settings file examples, please refer https://github.com/Azure/azure-api-management-devops-resource-kit/blob/main/src/README.md#extractor
Notes
- If while configuring code, “dotnet restore” does not work and if you start getting errors while calling “dotnet restore”:
- It means that required packages are not getting restored for below C# solution:
- In this case open ArmTemplates.csprj in Visual studio:
- Select “Manage NuGet Packages for Solution”
- Package source might be having “OfflinePackages” only as package source.
- To restore packages, we need to add online package source which will connect to “Nuget.Org” and download the required packages.
- Click on “Settings” icon besides drop down and click on “Plus” icon from below window.
- Make an entry matching below screenshot:
- After adding this entry, right click on solution and click on “Restore NuGet Packages”
- This will restore packages for the ArmTemplates solution, and you are good to run the Creator and Extractor commands now.
Common listed questions and answers:
Difference between Repository and APIM CICD approach.
Response:
- APIM Git repository is mainly used for backup and does not contain ARM templates.
- Azure APIM devops resource kit helps us to generate ARM templates using creator and extractor tools. This approach is recommended for large deployments.
How to extract APIM with Master /shared/ Service templates and linked templates.
Response:
- Please find below sample configuration to generate master template:
- Run Extractor tool with below configuration.
- To generate master template:
{
"sourceApimName": "DevAPIMInternal",
"destinationApimName": "DevAPIMInternal2",
"resourceGroup": "apim-rg",
"linkedTemplatesBaseUrl": true,
"fileFolder": "C:/Test/APIM_DevOPs/azure-api-management-devops-resource-kit- main/example/ExtratorSample/Output/linkedTemplates"
}
- Path specified in “fileFolder”, will be used to place generated templates using the tool.
Definitions
Service Templates
Contains all service level configurations of the API such as custom domain names, no. of scaling units, pricing tier, managed identity etc.
API Templates
For each APIM there are one or more api templates for the configurations of this API such as API definitions, policies, named values, diagnostic settings etc. Each of these templates can be deployed individually. To deploy single API, deploy template for that API. To deploy everything all together user master template which links to everything.
Shared Templates
For shared resources such as products, groups.
How can we deploy multiple apis using creator tool (how to specify multiple apis under “api:” array of creator tool?
Response:
Please refer below section from valid.yml (creator configuration file) where 2 apis have been specified in the “api:” array.
Generated output:
References