With the proliferation of APIs and microservices, it is more important than ever for businesses to effectively and consistently manage their APIs, and the API-Management service from Azure is designed to do just this. But how should you…manage…API-Management to meet the unique needs of your organization?
Enter GitOps for API-Management. This approach leverages centralized configuration management, automated deployments and seamless collaboration to deploy and maintain Azure API-Management as a centralized shared platform service. In this article, we will lay out this approach and show how it can help your organization achieve speed, security and scalability in managing your APIs.
- Speed: API developers should be able to publish their APIs quickly. This means the processes need to fit into the tools and workflows the developers are already using. New features to the platform service should also be rolled out quickly.
- Security: Every organization has its own standards and governance requirements around permissions, reporting, etc. The platform needs to enforce these, with transparency.
- Scalability: The platform needs to support increasing numbers of APIs and changing user requirements without compromising time-to-deployment or security of the APIs.
The following high-level diagram shows the main components that are built around the Azure API-Management resources themselves to make up the shared service. API developers and consumers are users of the shared service, and the Shared Service Team on the right is the team responsible for designing, implementing, and managing the service, as well as providing customer support and enablement. Let’s look at this in more detail, starting at the bottom right of the diagram. “Everything-as-code” is the order of the day.
The infrastructure repositories hold the configuration scripts for all Azure resources: the API-Management Service, virtual machine scale sets to use as build agents, network resources, as well as permissions-related resources: API subscriptions, keys, role definitions and assignments, etc. These configurations are validated via pull request validation pipelines and deployed automatically with release pipelines. Written in yaml and protected by policies, these pipelines allow the team to maintain consistent infrastructure across all stages, roll out or roll back changes quickly, and document all changes.
The API template repository, seen top right in the diagram, represents an API developer workspace template. An instance of the template is automatically deployed for each API developer team during the onboarding process. This provisions the provider with the resources on the left of the diagram: a dedicated Azure DevOps repository containing a sample OpenAPI specification and API policies to help them get started. Within this space, the provider has as much freedom as possible. Also deployed automatically with onboarding are a set of pipelines with which the provider can deploy their resources, and security groups on the basis of which access to resources is restricted via role-based-access control. Changes to provider infrastructure triggered by stagings or addition of new API consumers are also rolled out and documented automatically by pipelines.
Guidelines around API security and naming conventions required by the organization are enforced by an API linter service as follows. The company rule set is stored in a repository to which the API developers have read-access. A customized linter and online editor, adapted from the open-source Zalando repository, is deployed on an Azure App Service and linked to the API-Management Developer Portal as an external resource. This enables the developers to conveniently parse their API definition and receive immediate feedback about violated rules.
How does all this look from the perspective of an API developer? Compatibility with their usual workflow is important to supporting agility as well as adoption of the service.
When an API provider wants to make revisions to their API specification or to their API policy, they create a branch, make changes, and open a pull request. A few required checks on the pull request serve to enforce compliance with company standards. Most importantly, a pipeline validates the API specification against the API linter, and feedback is written as a comment in the pull request, listing any rules that are violated by the OpenAPI definition. The pipeline fails and the pull request is blocked from completion as long as there are violations of “MUST” rules. A “SHOULD" or “MAY” rule may be violated, but the developer has to manually resolve the feedback comment, providing an affirmation that they have seen and understood those violations.
Once those checks are successful, a second developer from the same team can review and approve the pull request. The PR is completed and the code is merged to main, as usual. This completion triggers a release pipeline, which documents the infrastructure change in a centralized change-management system for compliance with organizational documentation requirements. Finally, the changed API is deployed to API-Management following a successful health check of the endpoint. At this point, the API is available in API-Management Service and can be seen in the Developer Portal.
This process enables developers to bring to production new or changed APIs in a way that completely fits within their existing development workflow, speeding time to deployment. Moreover, the API developers can work independently here, allowing the platform to scale to more APIs without a direct effect on the capacity of the Shared Service team.
One last aspect can’t be overlooked: permissions management. Following the principle of least privilege, access to Azure and DevOps resources is, by default, blocked. For each API provider, dedicated security groups are created, and only members of these groups are given privileges. For example, there is a monitoring workbook provisioned for each provider, which can only be accessed by members of the corresponding Entra ID group. Only members of the appropriate DevOps security group have permissions to push changes to the provider repository, approve pull requests and trigger pipelines. All of these roles, policies and assignments are defined and managed by infrastructure-as-code. And, importantly, the provider is responsible for managing membership: the provider designates responsible persons, and only they have the ability to approve requests to join the group. The Shared Service team is responsible for the centralized technical provisioning and maintenance of permissions, but not for group management.
Centrally deploying API-Management with a GitOps approach like this offers significant benefits for an organization. API developers can work quickly and independently to bring APIs to production, with support from an expert team. From a security perspective, transparency around which data are being consumed by whom is achieved and compliance with standards is centrally enforced. Automation allows a small core Shared Service team to develop and deploy new features at the same time as meeting customer needs, in a scalable way.
