Innovation Norway (IN) is the Norwegian government's principal tool for encouraging innovation and the development of Norwegian enterprises. Their programs and services aim to enable entrepreneurs to successfully run scalable, innovative businesses.
In this article, we’ll go through how Innovation Norway automates the modeling of their microservices and integrations using Azure AD Service Principals, Microsoft Graph API and the Ardoq REST API. Take a look at the glossary section below for a quick introduction to these tools.
This customer story does not intend to be a best practice. It aims to spark new ideas for speeding up data modeling in Ardoq.
Table of contents:
Innovation Norway’s Objectives
As Innovation Norway modeled their architecture in Ardoq, they quickly realized they could leverage Ardoq’s REST API and their in-house engineering skills to automatically maintain a fresh architecture and help them understand the impact of change through dependency mapping.
They wanted to have access to good current documentation that would allow them to:
Have an improved governance
A better collaboration between business and IT
Free up resources so teams can focus on more impactful projects
They needed to automatically discover new components in their architecture and model how they were connected.
How Innovation Norway Is Achieving Their Goals
Maintaining an up-to-date architecture
To automatically model and maintain a detailed overview of their integration components, Innovation Norway developed an application called “Doc Master”. It runs every day and it queries the Microsoft Graph API to identify all the components or microservices that are deployed in their Azure production environment. Next, it fetches the Github repository .Readme file and the Github repository URL for each component and adds this new information as components and fields to Ardoq using the Ardoq REST API.
Creating an integration diagram
Organizations need to create integration diagrams to visualize which microservices are connected so they can understand and predict the impact of change. These integrations are detailed in the code. Thus, developers need to dedicate time to manually create the documentation that models the integrations that exist in the code.
To free up man hours and protect their developers’ time, Innovation Norway found a new way to use their application. The “Doc Master” now also queries the Microsoft Graph API to fetch all of Innovation Norway’s microservices access control permissions defined in their Service Principals and automatically discover the relationships between them. These relationships are then imported into Ardoq as references using the Ardoq REST API.
👉 Head over to Step-by-Step Guide: How Innovation Norway Automatically Models And Enriches Their Architecture.
Understanding How Innovation Norway Automatically Draws Integrations
The Microsoft Graph API enables Innovation Norway to access information about the:
Microservices that are deployed in their Azure instance
Access control permissions that protect each microservice
Access control permissions granted to each microservice. These permissions define the microservices each microservice in their Azure instance is allowed to access.
The Microsoft Graph API, however, does not know about the integrations that exist among the different microservices as they are hidden in the code.
To automatically recreate these integrations, Innovation Norway uses the access control permissions recorded in their Service Principals. Each microservice is protected by their own Access Control Permissions. For example, in the screenshot below, the microservice “Assets” is protected by the “Assets” access control permission.
By creating a 1-1 relationship between access control permissions and microservices, Innovation Norway is able to infer which microservice can access others. For instance, given that the “Assets” microservice is protected by the “Assets” access control permission and the “Customer” microservice is granted the “Assets” access control permission, they can infer that these two microservices are connected.
It is extremely important that each microservice is protected by their own access control permission so to not assume there is an integration where it is not. For instance, if the “Price” microservice is protected by the “Product” access control permission and the “Customer” microservice is granted the “Product” access control permission, you could assume that “Customer” can talk to “Price” but in reality it doesn’t.
To safely infer integrations among microservices, it is absolutely necessary that each microservice has their own access control permission.
Step-by-Step Guide: How Innovation Norway Automatically Models And Enriches Their Architecture
Automating the Modeling of Components and Integrations in Ardoq
To automate the modeling of their microservices and their integrations, Innovation Norway:
Deploys all of their microservice in Azure
Creates one access control permission per microservice
Grant microservices other microservices’ access control permission so they can access each other.
Set up a daily import from Microsoft Graph API that fetches the data below using the Doc Master application:
The microservices deployed in Azure
The Service Principals that contain the access control permissions that protect each microservice
The Service Principals that contain the access control permissions that are granted to each microservice
Next, the Doc Master application infers the integrations by looking at the Service Principals each microservice is protected with and granted. For example:
The “Order” microservice is protected by the “Order” Service Principal.
The “Order” microservice is granted the “Price”, “Assets”, and the “Customer” Service Principals.
Thus, we can infer that the “Order” microservice can talk to the “Price”, “Assets”, and “Customer” microservices.
Finally, the Doc Master application pushes this data into Ardoq using the Ardoq REST API. The data is imported into a new workspace called “Service Layer”.
Automating the Import of Github Repositories into Ardoq
Innovation Norway imports information from their Github repositories to enrich the documentation in Ardoq. The Azure APIs and Functions are imported as components into the “Service Layer” workspace and enriched with:
A description field that details the contents of the Git repository readme file.
A URL field linking to the API or Functions Git repositories.
Innovation Norway's naming standard ensures that the APIs and Functions are matched with the repo URLs.
The description field allows the consumers of Ardoq presentations to have easy access to an updated description of what each API and Function does, what technology is used, and what data is processed:
The URL field enables developers to have easy access to the Github repositories through the links on the components in Ardoq presentations.
Outcomes
Automating the modeling of microservices and integrations translates to a good current documentation that enables a better understanding of the architecture.
Business and IT transparency. Business stakeholders and product owners can better understand the complexity and impact of their proposed changes. They can now:
Better estimate costs and time it would take to deliver a project or implement changes
Make data driven decisions
IT teams can now effectively communicate with business leaders and guide decision-making.
Governance and control.
IT security teams can visually inspect permissions, making it easy to see when access is given when it should not have been.
It allows clear lines of ownership by having an always updated microservice asset and the owners in Ardoq.
Innovation Norway’s approach can be applied by organizations using Amazon Web Services (AWS) as they have a similar concept for authorization to Service Principals called “Principals”.
If following this approach, we recommend considering the number of Service Principals you need and how much maintenance work they would require.
Glossary
Tool | What is it |
Doc Master | Doc Master is the application Innovation Norway developed to automatically import their microservices and integrations into Ardoq. |
Microsoft Graph API | The Microsoft Graph API is a RESTful web API that enables you to access Microsoft Cloud service resources.
Innovation Norway uses the Microsoft Graph API to access their Azure data through the Doc Master. |
Service Principals and Access Control Permissions | Service Principals define the permissions of the microservices that are connected and allowed to access each other. These permissions are called “Access Control Permissions”.
Innovation Norway uses Service Principals to infer existing integrations. |
Azure | Microsoft Azure is Microsoft's public cloud computing platform. It offers cloud services, such as compute, analytics, storage and networking.
Innovation Norway has their microservices deployed in an Azure instance. |
Github | GitHub is a code hosting platform for version control and collaboration.
Innovation Norway imports information from their Github repositories into Ardoq using the Ardoq REST API so they can enrich their architecture. |
Ardoq REST API | Ardoq’s REST-API enables you to integrate with Ardoq. You can use it to automate documentation, or to create custom tools that make use of data from Ardoq.
Innovation Norway uses the Ardoq REST API to import Azure and Github data into their Ardoq organization. |