Understanding how the internal developer portal and platform connect

Understanding how the Internal Developer Portal and Platform Connect

Introduction

Platform engineering is a broad term, and includes many moving parts and confusing terminologies, categories and underlying architectures. To implement it, you need to plan, piece different tools together and think about the developer experiences and golden paths you want to deliver. 

Numerous articles have been written about the difference between an internal developer portal and platform, and about the delineation between them, but I want to go a step further to explore how they connect.

In this post, I will answer the following:

• What is a platform 
• What is the role of the Internal Developer Portal in relation to the platform; and 
• What are the APIs through which platform and portal connect, and what is the resulting orchestration

Let’s begin by understanding the stack:

• Platform
• Portal; and 
• API

Platform: what is an internal developer platform?

My answer to this question is simple: a platform is made of everything you’ve already built into your SDLC, as well as your infrastructure, cloud and everything in between. This will include:

• IaC
• Git provider
• K8s
• 3rd party tooling
• CI/CD pipelines
• Feature flagging and gradual rollout implementations
• Security practices and tooling
• Microservices architecture
• Cloud infrastructure
• Incident management
• Observability and so on. 

It is the sum of the platform tools and infrastructure you already have.

 In other words, you already have a platform in place.

The next question you may be asking is: “if I have a platform, why do I need a portal”. 

The answer is that the internal developer platform is made of many moving parts, and to interact with them and be self-sufficient, developers need to know quite a lot about the elements that make the platform up. Usually, they don’t and therefore they are not self-sufficient, and as a result they either waste time or create endless tickets to DevOps. The developer portal is here to solve this problem. 

Portal: what is an internal developer portal? 

Internal developer portals enable developers to gain autonomy without having to concern themselves about the complexity of the infra and tools surrounding application delivery.They reduce cognitive load on developers by providing an abstraction of your software and infrastructure – so that developers can easily make sense of anything in the stack and the resulting interdependencies.

An internal developer portal also assumes that you already have some level of a platform implementation in place. If you are a part of a 50-person (or more) engineering organization, chances are that you already have a platform in place and are ready to adopt a portal.

The portal will connect to your platform and do the following:

1. Improve visibility. Take your metadata and create a software catalog that provides rich context that is directly tied to your Software Development Life Cycle. For example, the software catalog can include real-time data from K8s to show the runtime information on each microservice deployed in each environment.
   
   
2. Enhance autonomy  The portal drives developer autonomy by offering them a suite of self-service actions. These actions serve practical day-to-day developer needs such as provisioning new services or acquiring temporary permissions for cloud resources. This streamlines workflow and accelerates development processes. This is the area where we’ll be focusing on in this blogpost, since this is where the more interesting interplay between the platform and the portal take place.
   
   
3. Promote organizational quality and compliance: The portal plays a crucial role in ensuring that developers are not just “writing code” but are driving organizational standards and KPIs. It facilitates a 'shift-left' approach in addressing security, quality, and operational concerns. By equipping developers with the right insights, the portal helps them make informed decisions to deliver products that are not only faster and safer but also of higher quality.

But how does the Portal interact with the platform? The answer lies in understanding the platform API (or APIs 🤔)

The platform API

Every application you have probably ever written is made of three parts:

• The front-end 
• The backend; and 
• The backend API (REST).

In platform engineering, you can think about the platform API as the “Backend API” for your portal. This is what will make the platform accessible to the portal, so it can query data, execute actions etc. For example, a developer that wants to scaffold a microservice will execute a self-service action on the portal, and the portal needs an API to trigger that action in the platform.

The answer to the API question seems simple to us:  The portal connects to the numerous APIs of the platform’s existing tools and infrastructure, and collects this information within the portal. 

How the platform APIs connect to the portal

This approach uses the existing APIs of the tools that make up the platform and orchestrate everything from the portal itself. Let’s review the main tools and how their APIs are used:

1. CI/CD

CI/CD usually plays a role in exposing an API to the portal.

When it comes to developer self-service actions, you can usually use your existing CI/CD API (such as github actions) to connect to the portal. In other cases, you would want to implement your own actions, which will often incorporate an IaC implementation in addition to various other steps. 

2. GitOps

The git provider is another API exposed to the portal. Executing actions by performing a git change is often best practice. In addition, reading manifest files from the git and showing them inside the portal with context will enrich the software catalog. The list of examples goes on. 

3. Engineering Tooling

The entire devtool stack also plays a crucial role. Each dev tool holds relevant information about the SDLC, can enable developers to perform various actions on their own through self-service, and maintains relevant insights means that all dev tools are part of the platform. 

Let’s take Feature Flag tools as an example. They are an important part of the platform, and should be considered as another API into the portal. The capabilities include:

• Being able to see feature flags that are activated/deactivated for each running service
• Toggling feature flags for a running service
• Connecting to your observability tools and automatically switching a flag on or off if your tools detect a critical service issue
• Declaring a feature flag prerequisites check to a Production Readiness scorecard to ensure flags only get activated in the right situations

The same goes for so many other features such as: monitoring & observability, on-call tools, AppSec & cloud security, FinOps and cloud cost management, consumption of IaC, incident response, permission management, API catalogs, ticketing tools, SaaS management, and more.

4. Cloud

Cloud providers play an important role in the platform, mainly for observability reasons. It’s pretty obvious that providing developers with direct access to the cloud console is bad practice. Therefore, we'd want to visualize the resources (in context) in the software catalog, and then enrich it with other data brought from other platform elements.

5. IaC

IaC is another API endpoint to the platform, especially since IaC often abstracts many other platform pieces such as cloud resources or K8s. You often enjoy an API exposed out of the box from your IaC tool. If we take Terraform or Crossplane as examples, you can use Terraform cloud or Upbound’s API to interact with your platform. In addition, bringing data from your IaC execution run can enrich the portal with relevant information about provisioned, terminated or modified resources you would like to inform your developers about.

6. K8s

K8s is becoming the ultimate platform and will soon abstract everything under one umbrella. At least this is where the market seems to be headed. Portals should work seamlessly with the K8s API, since it is crucial to abstract away K8s complexity for developers. The software catalog greatly benefits from bringing live K8s data in context to the SDLC representation inside it. 

Where does orchestration happen?

Let’s first define “orchestration”. To us, it’s made of two parts:

1. A unified interface for developers where they can consume and find everything they need: The interface enables you to create business processes that take the developer through the SDLC, step by step. This workflow, which contains many steps, is defined within the portal (check PR approval, show the merge, deploy to staging etc) and is essentially “orchestrated” in the portal. 
2. Triggering the desired behaviors using the platform tools: an Interface with the different platform tools to run, schedule and monitor an action.

Here are some examples of orchestration in practice:

• Declaring the process of shipping an application or a feature to production and making sure the developers do not deviate from it
• Automating runbooks 
• Terminating resources with built in TTL (for ephemeral environments use cases)
• Managing permissions of platform users
• Blocking a deployment of a feature to production if a certain set of requirements is not met
• Executing a runbook in case manager approval is required (thus also tracking manual approvals)

When you think about a Portal and a Platform, it's not obvious where orchestration belongs. You can make two arguments:

• Orchestration belongs in the platform: the platform executes jobs and performs the runtime of the different platform elements. Therefore, it makes sense to have the orchestration piece embedded within the platform and “hide” the actual orchestration behind the API. In this case the orchestration can happen either through the “internal developer platform tool/orchestrator” or through the many APIs within the platform’s components. 
• Orchestration belongs in the portal: the portal acts as a single source of truth of the SDLC. In addition, it's where you define the self-service experience itself, therefore it would make sense to have orchestration carried out by the portal, since it already has the right context and is integrated into powerful tools like Github workflows and other existing platform pieces.

My argument is that the portal - despite being loosely coupled from the platform - is the best option as a de-facto orchestrator. The portal is superior when it comes to working with the various platform APIs:

• The software catalog is a single source of truth as to the state of the platform and can include logs, manual approvals and more
• It triggers actions in the platform when a developer executes a self-service action, all according to the golden path defined by platform engineers. 
• It triggers smart workflows, for instance when a developer sets up an environment with a TTL. One trigger sets it up and then a workflow automation flow, which is defined in the portal too, will terminate the environment in time. 

As a result, I believe that the right approach is to use the platform APIs, and not a specific platform tool/orchestrator. As we know, you’re already likely to have a Platform which consists of existing APIs, and Gartner predicts that by 2026, 75% of organizations with platform engineering teams will provide internal developer portals (up from 45% in 2023), so the portal’s strength in connecting to APIs would effectively make the platform tool/orchestrator redundant.

To better understand this let's look at the architecture:

‍

‍

Conclusion

To conclude, in formulating your platform engineering strategy, a Portal is effective when used together with the platform’s different APIs. Opting for a portal alone offers the benefit of a unified integration point with all of your other tools, simplifying the process. Conversely, the alternative approach (using the platform orchestrator/tool) necessitates integrating multiple components at various intersections. It is best to steer clear of unnecessary complexity and strive for simplicity.