How Do the Internal Developer Platform and Portal Connect?

We see a lot of articles that explain the difference between an internal developer platform and an internal developer portal. While it’s important to make a distinction between the two, it’s more useful to know how the two connect because, quite frankly, a platform without a portal won’t make developers’ lives easier. Platforms need a frontend, and that is the role of the internal developer portal.

Let’s look at what a platform is and the role of the portal in relation to the platform and finally, the APIs through which the platform and portal connect.

What’s an Internal Developer Platform?

Without even knowing it, you’ll probably already have a platform in place. An internal developer platform is essentially made of everything you’ve built into your software development life cycle (SDLC), along with your infrastructure, cloud and everything in between. The platform is the totality of the platform tools and infrastructure you already have.

The platform is a central hub made of up the tools required to build, deploy and manage everything, with the chief goal of improving developer experience. For example, a platform offers unified access to internal APIs, microservices, SDKs and other resources needed for development. It also provides integrated tooling like CLI tools, build automation, CI/CD pipelines and infrastructure provisioning.

This means the developer does not need to work directly within a third-party tool such as incident management, appsec or FinOps. Instead, the developer accesses these tools through the platform.

The main purpose of an internal developer platform is to reduce developers’ cognitive load by centralizing resources and making them more accessible.

So Why Would You Need a Portal as Well as a Platform? 

Platforms help with abstracting away complexity, but they don’t go far enough. They have limitations around accessibility, scalability and the necessary guardrails for developers. A platform can still be difficult for developers to get their heads around, meaning they can’t be self-sufficient, and this affects the time they spend on working things out, asking for assistance or creating tickets to DevOps.

An internal developer portal further abstracts away complexity and promotes developer self-service, all while providing golden paths and ensuring the relevant guardrails.

So What Does an Internal Developer Portal Do?

The portal acts as a user-friendly interface to the platform, abstracting the complexity of the software development environment by providing a single user interface that’s built for the questions and needs of different dev teams, so they can easily make sense of the entire tech stack and the resulting interdependencies. Essentially, they’re tailor-made for better developer experience and productivity.

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

• Ingest your metadata and create a software catalog to provide you with the context you need. It will be where everything about your software development life cycle lives — applications, services, environments, resources — and it will contain information about each like owners, documentation and other context. For example, the software catalog can include real-time data from Kubernetes (K8s) to show the runtime information on each microservice deployed in each environment.
• The portal drives developer autonomy through a suite of self-service actions. The key benefit of self-service actions is freeing developers from repetitive, time-consuming work. Platform engineers create the actions using the portal and put in place flexible guardrails around them. This way, developers can provision new services or acquire temporary permissions for cloud resources without requiring assistance. As a result, this streamlines workflow and accelerates development processes.
• The portal ensures 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 (through scorecards), the portal helps them make informed decisions to deliver products that are not only faster and safer but arebalso of higher quality.

How Does the Portal Interact with the Platform?

If the platform is made of the many tools used for the SDLC, and the portal is the frontend, we now need to define the API through which they both connect. When a developer executes a self-service action in the portal, how does it get communicated to the underlying platform?

This is the API the portal will use to trigger a specific action in the platform, enabling self-service actions such as scaffolding a microservice or provisioning a cloud resource. It is the same API that will be used to create the software catalog.

While some argue that the portal needs a central API (an “orchestrator”) to connect to the platform, I believe that the API that the portal triggers is not one, but many — the existing APIs of the platform’s existing tools and infrastructure.

How Do the Platform APIs Connect to the Portal? 

Let’s examine these platform APIs.

CI/CD — You can use your existing CI/CD API, such as GitHub actions, to connect to the portal for developer self-service actions.

GitOps is another API exposed to the portal, and executing actions by performing a git change is often considered best practice. By reading manifest files from the git and showing them inside the portal with context, you can also enrich the software catalog.

Engineering tooling — The entire devtool stack also plays a pivotal role. Each dev tool holds relevant information about the SDLC, enabling developers to perform various actions on their own through self-service and maintain relevant insights.

Feature flags are one of those devstack tools and should be considered as another API in the portal as it would enable users to see feature flags that are activated/deactivated for each running service, connect to observability tools, automatically switch a flag on or off if a critical service issue has been detected and more.

Other features also hold relevant information about the SDLC: monitoring and observability, on-call tools, app and cloud security, FinOps and cloud cost management, consumption of infrastructure as code (IaC), incident response, permission management, API catalogs, ticketing tools, SaaS management and more.

IaC is another API endpoint to the platform, and the API is often already exposed out of the box. For example, 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 keep your developers informed about.

K8s — Connecting with the K8s API is crucial to abstract away K8s complexity for developers. The software catalog becomes more complete and rich by bringing in live K8s data in context to the SDLC representation inside it.

Finally, 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, then enrich it with other data brought from other platform elements.

Here are different examples of actions that can be done using an internal developer portal:

• 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 Time to Live (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)

Where Does Orchestration Take Place?

So far we’ve described two steps:

1. The portal acts as a unified interface where developers can consume and find everything they need. In other words, where they can “orchestrate” business processes that take the developer through the SDLC journey, step by step. This workflow — which includes checking pull request approval, showing the merge, deploying to staging and more — is defined within the portal and “orchestrated” in the portal.
2. The portal then triggers platform tools through their respective APIs, to run, schedule and monitor an action.

It may not seem obvious where orchestration belongs.

The portal is best working with the various platform APIs. This is because it uses the software catalog as a single source of truth for the platform and it can incorporate logs, manual approvals and more. The portal can also trigger actions in the platform when a developer executes a self-service action in GitHub actions or any other tool and this can align with the golden path defined by platform engineers. In addition, it can trigger smart workflows, an example of which is when a developer sets up an environment with a TTL. One trigger sets it up and then a workflow automation flow (defined in the portal) will terminate the environment in time.

As you’re already likely to have a platform that consists of existing APIs — and because most organizations (75%) with platform engineering teams will provide internal developer portals (according to Gartner) — it means that the stronger approach is to use the portal’s strength in connecting to APIs directly, effectively making the platform tool/orchestrator redundant.

As a result, the API between the portal and platform would look like the below diagram:

👁 Image

The Portal Provides Simplicity

Platform engineering is all about reducing complexity and improving developer experience. Opting for a portal for your orchestration needs will go some way toward that. The portal offers the benefit of a unified integration point with all of your other tools, simplifying the process. In contrast, a specific platform orchestrator/tool necessitates integrating multiple components at various intersections, adding another layer of complexity to your platform. If you want to stand by your platform engineering principles, then it’s a straightforward choice for which option you’d use for your orchestration needs.