Headerbild

eBizTalk - Berichten, Unterhalten, Weiterbilden

Ob Branchendiskurs, Fachartikel oder ein Blick hinter die Unternehmenskulissen: eBizTalk ist die Plattform, die uns auffordert, unsere Leser über Events und Projekte auf dem Laufenden zu halten. Und uns gegenseitig natürlich auch.

API Management Part 7: Tagging of APIs in Azure

Veröffentlicht am 30.12.2020 von Hieronymus Deutsch

This article is the 7th in a series about API Management. It aims to uncover the complexities that might come your way when considering introducing API Management in large organisations. This part is a bit of a side-track to this. In recent days I came across the requirement to design a solution where APIs of different organisational units share the same API Management system (Azure API Management). The challenge was to define a way APIs can be managed and usage of the common infrastructure can be evaluated for future cost-splitting between the business units.

Of cause, we use tags to manage resources

The decision on how to enable management of resources was an easy one. Of cause, we use tags for this.

Naming conventions and tagging are ways to add information and meta-data to your cloud infrastructure component to make them easily searchable and manageable. The benefits are also confirmed by the Microsoft Decision Guide of the Cloud Adoption framework.

  • Resource management

- Ownership, environments... These tags make it easier to find resources

  • Cost management and optimization

- Cost allocation and budgeting can be enabled through tags

  • Operations management

- SLA information in a tag is important for operations

  • Security

- Confidentiality information for example can help when confirming access permissions

  • Governance and compliance

- Governing policies can be managed and applied using tags.

  • Automation

- Information relevant for automatic maintenance can be saved in tags. One example is “ExpireOn: …" resources could be automatically deleted at that date to reduce infrastructure costs.

  • Workload optimization

- Information about which processes require the resource enable a deeper and quicker analysis to resolve overarching issues

The following chart also illustrates the benefits clearly.

Source: https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/decision-guides/resource-tagging/

Ways to add tags 

Now that we established that it is useful to tag your resources and that APIs are no exception to the case, we look at how this can be done.

As adding a tag to a resource is part of “managing your resources” the ways of adding tags are equal to the ways of how you would provision resources, which can be as follows:

1. Portal/ User interface of cloud provider

2. Application Programming Interface (API) of the provider

3. Infrastructure as Code solution supported by the cloud provider. (see my other articles about IaC)

Additionally, specific to Microsoft Azure you can use the following:

4. In Azure you can use the “Azure Cloud Shell”

5. In Azure you can also use the PowerShell “AZ” Library

6. Azure Resource Manager templates (ARM-templates)

This might seem like a lot. And, frankly, it is. The freedom offered by this bouquet of option is necessary, however, to fill the need of every larger organisation with security or operational constrains.

Below image describes how the different ways integrate with Azure. It shows the four ways of resource management offered by Microsoft. Other ways build on top of this. If you have been thinking about using terraform for example, it builds on top of the Azure CLI.

Source: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/overview

Microsoft claims that those methods are at least as powerful as the Azure portal if not more so as it takes up to 180 days to implement some features in the portal. (src) This is not always true I found, but more on this further down.

Adding tags via... the Portal

The first and most straight forward way is by accessing the management portal of your cloud provider. In azure this is portal.azure.com. Below screenshot illustrates where to change tags of an API Management resource in the azure portal if needed.

This screenshot illustrates where to change tags of an API.


This might be a comfortable way of doing it the first time around. But considering larger organisations, every time one of those properties change that have been added as a tag, someone needs to manually go into the portal to update those tags. This might not be the desired solution for many.

Adding tags via … PowerShell & CLI

I will be looking at PowerShell in this part as the CLI and PowerShell are very similar.

Before you can manage resources, you need to install the az module PowerShell needs to enable Azure resource management. Once PowerShell is prepared you can add tags to Azure resources using blow PowerShell snippet as example. It adds tags to the resource. A similar example for how to accomplish this using the CLI can be found here.

``` PowerShell

$tags = @{"Dept"="Finance"; "Status"="Normal"}

Update-AzTag -ResourceId $resource.id -Tag $tags -Operation Merge

```

HOWEVER, and this is the critical part when talking about APIs, this needs to be supported by the data-model of the resource.

Looking at the model of an API Management you can see that it supports tags to be assigned:

..

Location                          : West Europe

Sku : Consumption

...

SystemCertificates        :

Tags                                 :{}

AdditionalRegions         :{}

….

Looking at the model of API resources however shows that here the Tag property is missing:

ApiId                         : 691b7d410125414a929c108541c60e06

Name                          : echoapiv4

Description                   : Create Echo Api V4

ServiceUrl                    : https://echoapi.cloudapp.net/v4

Path                          : echov3

ApiType                       : http

Protocols                     : {Http, Https}

AuthorizationServerId         :

AuthorizationScope            :

OpenidProviderId              :

BearerTokenSendingMethod      : {}

SubscriptionKeyHeaderName     : Ocp-Apim-Subscription-Key

SubscriptionKeyQueryParamName : subscription-key

ApiRevision                   : 1

ApiVersion                    : v4

IsCurrent                     : True

IsOnline                      : False

SubscriptionRequired          : True

ApiRevisionDescription        :

ApiVersionSetDescription      :

ApiVersionSetId               : /subscriptions/subid/resourceGroups/Api-Default-West-US/providers/Microsoft.ApiManagement/service/contoso/apiVersionSets/xmsVersionSet

Id                            : /subscriptions/subid/resourceGroups/Api-Default-West-US/providers/Microsoft.ApiManagement/service/contoso/apis/691b7d410125414a929c108541c60e06   

ResourceGroupName             : Api-Default-West-US

ServiceName                   : contoso

This missing property has the logical effect that you CAN NOT add tags to APIs via PowerShell. This issue is reported to Microsoft and is currently open.

Adding tags via … REST

Looking at the alternative ways of managing resources in Azure the Management API of Azure comes to mind. This is a REST endpoint offering about the same functionality as PowerShell’s Az module does.

The documentation of the operation we need to add tags to an API Management resource can be found on the documentation website of the same.

Now looking at the endpoint to manage APIs you can see that there is, again, no tag property available. Microsoft instead offers a separate endpoint to manage tags of an API.

The process of adding a tag to an API is as follows:

1. Create a tag entity in API Management – link

2. Assign the tag to the API or Operation – link

3. To list tags an API has there is another endpoint – link

Although this might be inconvenient and not very user-friendly, I for my part am happy that it is at all possible.

Adding tags via … ARM

When looking at how tags are added to APIs via the REST API(s) we can assume that tags are separate resources that need to be created and then linked to other resources. This becomes obvious when looking at the ARM templates.

API Management as the parent resource template has APIs and those in turn Operations and, you might guess it, tags as child-resources. But you need to watch out here. This is also a reference to the tag resource. You therefore need to also create the resource of the tag.

The following example would create an API Management with one API (and no operations) where the API displays a single tag “exampletag”.

{

    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

"contentVersion": "1.0.0.0",

    "parameters": {

    },

    "functions": [

    ],

    "variables": {

    },

    "resources": [

        {

            "apiVersion": "2017-03-01",

            "name": "Your API Management",

            "type": "Microsoft.ApiManagement/service",

            "location": "West Europe",

            "tags": {

            },

            "sku": {

                "name": "Developer",

                "capacity": "0"

            },

            "properties": {

                "publisherEmail": "mail@mail.com",

                "publisherName": "Your Name"

            }

        },

        {

            "name": "An API",

            "type": "Microsoft.ApiManagement/service/apis",

            "apiVersion": "2019-12-01",

            "properties": {

                "displayName": "Example API Name",

                "description": "Description for example API",

                "serviceUrl": "https://example.net",

                "path": "exampleapipath",

                "protocols": [

                    "HTTPS"

                ]

            },

            "resources": [

                {

                    "name": "YOUR_TAG_NAME",

                    "type": "Microsoft.ApiManagement/service/apis/tags",

                    "apiVersion": "2019-12-01"

                }

            ]

        },

        {

            "name": "YOUR_TAG_NAME",

            "type": "Microsoft.ApiManagement/service/tags",

            "apiVersion": "2019-12-01",

            "properties": {

"displayName": "exampletag"

            }

        }

    ],

    "outputs": {

    }

}

Adding tags via … other IaC’s

I have checked Terraform and Ansible and am sad to say that neither support API tags. This is because Terraform for example uses the CLI in the background to communicate with Azure and this does not yet have this “feature.”

Unlike with Ansible, using Terraform you can manage APIs and operations. And if any functionality is not available in terraform it does provide the convenient feature of being able to use ARM templates to deploy resources. And those do support tags.

The impact

Although there are many ways, as specially for Azure, to add tags to an API, and most of them are to support automation, not all of them allow this. The impact is that not all use cases are supported.

One of those might be: extending an existing PowerShell script that synchronises APIs with a Data Catalogue (if this feels oddly specific to you, read part 6 of my series). It came as quite the surprise that it was not natively supported by the PowerShell module. It does feel as quite the workaround having to use the API here, but that is just my opinion.

Another use case, thinking of IaC (Infrastructure as code), is that when a workaround needs to be used, the solution becomes unclean and might even introduce unexpected behaviours or related issues.

The reason

Finding the reason for the inconsistent behaviour required a deep dive into the documentation and still I can only voice a hunch. Microsoft correctly claims that APIs support tags. This can be seen on this lengthy list of resources that do not support tags: LINK. The limitations listed on the page of “How to use tags” have one small point, I nearly overread, that states “Tags can't be applied to classic resources such as Cloud Services.” This implies the existence of “Classic resources.”

This is the part where I start guessing. I believe APIs had tag support from the start when they were still a classic resource. When introducing the new resource model type, they (Microsoft) did not update the APIs as the feature was already implemented at the time. This old way of doing it requires us to create a tag resource before assigning it to a resource. Because this is a legacy process it was omitted when implementing the SDK for PowerShell or the CLI.

Facit

Tags are useful to manage, support and secure your APIs. If it is for cost-splitting or for tracking down data due to GDPR requirements, tags can hold relevant information that makes it much quicker and easier to fulfil those tasks.

APIs are no exception there. APIs are however the exception when it comes to tooling consistency and does require a workaround from the developers.

If you want to help solve this problem, you can do so by “liking” the issue that was raised with Microsoft on this topic.

google_about_ebiz fb_about_ebiztwitter_about_ebizxing_about_ebiz