What is an internal developer portal?

What is an Internal Developer Portal?

An Internal Developer Portal (IDP) is the engineering system of record for tracking, improving, and building high-quality software. From services and APIs to Kubernetes clusters and data pipelines—IDPs abstract away the complexities of ensuring software security, maturity, production readiness, and more—all using data from your existing tools.

Much has been written about Internal Developer Portals, but in this space we’d like to provide a little more depth on foundations, critical capabilities, use cases, and even suggested onboarding plans. We hope it’s useful!

What do Internal Developer Portals solve?

Engineering leaders are faced with new complexities introduced in the last five years of technological innovation. Microservices, containerization, and multi-monolith initiatives have become extremely popular amongst organizations aiming to improve the speed and scalability of software development.

In parallel, the explosion of new SDLC tooling to cater to these new environments have left development teams weighed down by process, alert-fatigue, and data inconsistency. These two changes mean engineering teams now need to:

1) Reduce the cognitive load while improving developer productivity,

2) Increase software quality and observability,  and

3) Speed time to market in an increasingly competitive atmosphere

Internal Developer Portals emerged to address all three. And while adoption in organizations with platform engineering teams was estimated at an impressive 45% in 2023, Gartner projects a staggering 75% penetration by 2026, according to their latest Market Guide on Internal Developer Portals. This statistic is even more impressive given the fact that IDPs(or more accurately service catalogs at the time), only made their debut around 2018. Even the most popular opensource Internal Developer Portal, Backstage, has just shy of three years on the shelf!

What’s the difference between an Internal Developer Portal and an External Developer Portal?

Pre-dating Internal Developer Portals, External Developer Portals are repositories of information and resources for developers who are using another company’s APIs. These portals give API teams access to support in the form of information concerning the APIs. Companies feature developer portals (dev portals) and forums on their websites, and these are spaces where you can explore new API products with the support of extensive knowledge resources and support.

Internal Developer Portals emerged to provide similar levels of support and documentation for internal use cases—to provide cataloging, scoring, and production readiness tools that enable developers to work more efficiently, and consistently. It should be noted that Internal Developer Portals can also manage APIs for internal use, similar to how external portals manage access for external users.

What’s the difference between an Internal Developer Portal and an Internal Developer Platform?

We dive into this topic in a little more depth in another blog comparing portals to platforms, but in short, an internal development platform helps provide structure to a company's software delivery process.

The main capabilities offered by Internal Developer Platforms to ensure safe, observable deployments include:

• Infrastructure and access control provisioning
• Orchestration and monitoring of CI/CD pipelines
• Deployment best practices or "golden paths"

Internal Developer Portals can complement, or sometimes partially eclipse the capabilities of Internal Developer Platforms, depending on an organization's use case.

The main capabilities offered by Internal Developer Portals to ensure consistent application of data and standards includes:

• Software catalogs that integrate and standardize data from across the SDLC‍
• Centralized standards for scoring software quality, readiness, and program progress‍
• Templates to bootstrap new software that means standards of excellence

The system of record offered by Internal Developer Portals fuels more robust and consistent deployment pipelines offered by Internal Developer Platforms.

Who uses Internal Developer Portals?

Developers perform day-to-day operations either within IDPs or driven by data from IDPs infused into their normal workflows, but many different stakeholders benefit from use:

• Developers: Developers use IDPs to quickly understand software they own or have access to, reduce time to respond by understanding documentation, changes, and dependencies in one place, prioritize tasks to close gaps in software health or respond to changes needed, and leverage templates to bootstrap new software according to best practice
• Engineering leaders: Internal Developer Portals help engineering leaders build confidence in alignment to organization standards, improve the security and reliability of software, and even provide insight for project resource allocation and planning.
• SREs: Reliability engineers use IDPs to set enforceable standards of quality and reliability, reduce overhead for devs in coming into compliance with initiatives, manage on-call rotations, and reduce time to respond by investigating context from within the platform.
• Platform Engineers: Because Platform engineers build tools and workflows to support efficient software development, they may focus more on the “last mile” of IDPs that focuses more on self-service functionality like software scaffolding against core standards.
• Developer Experience and DevOps/DevSecOps: As teams are responsible for easing the cognitive load for developers while ensuring safe and scalable practices in software development, IDPs are fantastic tools to abstract away complexity while enforcing standards.
• Security: Security teams have a vested interest in ensuring software is “set up for success” to reduce risk and ensure rapid response when vulnerabilities inevitably occur. These teams can share minimum requirements for things like connection to vuln scanning, and code coverage tools, or help set thresholds for maximum number of unresolved issues.
  

What are the core components of an Internal Developer Portal?

The primary user of Developer portals are of course, software developers—but that doesn’t mean other groups like SREs, platform engineers, DevEx, DevOps, and Security don’t have a critical role to play in optimizing that experience. With such a wide variety of stakeholders, it’s easy to see how product strategy for IDPs has diverged from provider to provider.

However, in recent years we’ve seen a coalescing of functionality. It’s now a relatively unchallenged truth that IDPs should consist—at minimum—of three core capabilities:

1. The ability to catalog software components
2. The ability to score software by standards of deployment readiness, health, and maturity
3. The ability for developers to self-serve software production according to such standards

Software Catalogs

Before we get to software catalogs, it’s important to start with their predecessor, service catalogs. These solutions were created to help manage the sprawling and dynamic complexities of microservice ecosystems by providing engineering teams with a central system of record for service functionality, owners, dependencies, and documentation—the sorts of details not captured by existing ITSM or monitoring solutions, and often left to manual tracking via spreadsheet or shared wiki.

Perhaps the most important role of software catalogs, however, is in the role they play in software optimization. Hydrating your catalog with information from across the stack is the first step forward in benchmarking quality, consistency, and use. It’s impossible to have any confidence in software reliability, consistency, maturity, or security if you’re not exactly sure where things live, who owns them, or what they're made of.

Types of catalogs

Service catalogs still serve a purpose, but have waning relevance as a stand-alone solution. We now know architectural complexity comes in many forms—from microservices to multi-monoliths, and the components related to services are numerate and equally in need of greater attention to quality and consistency.

Software catalogs enable organizations to capture and manage details related to any type of software component, entity, or artifact, including: Services, ML models, Kafka topics, Infrastructure, Data pipelines, On-prem servers, APIs & endpoints, Third party vendors, K8s clusters and nodes, Frontend react components, Internally deployed tools/platforms (like Jenkins or hashicorp tools), built artifacts like docker images or versions of services running in different environments... and anything else you can dream up for your SDLC.

Catalog ownership and discovery

Understanding ownership is one of the most important use cases for software catalogs. But ownership isn’t the easiest problem to solve. People join and leave organizations, switch projects, transfer teams, get promotions... and with these changes come changes in responsibility for software as well as access rights. Internal Developer Portals must integrate with identity and RBAC (role-based access control) platforms to ensure always-up-to-date ownership information.

In addition to providing ownership information, software catalogs must also enable users to answer nuanced questions like what’s currently running, what it does, what language it was written in, what version it uses, what changes have been committed over the last week, who’s on call to support it, and what to do during an incident. By offering on-demand context on each software entity, IDPs help reduce risk, accelerate time to remediate, and reduce time to onboard.

Software Scoring

What enables software catalogs to provide such rich context on component state and dependencies can also be wielded to ensure continuous consistency in security, maturity, efficiency, and more.

While the ability to score software for alignment to best practice was first introduced by Cortex in 2018, it has since become a table-stakes feature in any IDP. The idea of continuous scoring has become particularly important as change velocity for software steadily increases—whether its to add functionality, eliminate complexity, or reduce risk when vulnerabilities are discovered, versions need patching, or an EOL requires immediate upgrade.

Types of scorecards

Some internal developer portals, like Cortex, come with an expansive set of integrations to top SDLC tools. Not only does this data provide depth and breadth to catalog contents, it can be used to create scorecard rules and levels that lets users quickly assess how software stacks up against organizational standards.

Cortex’s scorecards can leverage data from any out of the box integration, or custom data from internal tools or unsupported third-party vendors. This is why we see such a wide variety of scorecard types across all of our customers, but here are just a few that tend to pop up regardless of company size, organization, or priority:

• Operational Maturity: Operational maturity scorecards might look at things that DevOps teams are keen to track like like presence of a README, defined owners, automated testing, code coverage, and defined on-call rotation
• Health: This scorecard might look at things like number of open Git (GitHub, GitLab, etc)/Jira issues, Latency metrics, static analysis frequency, uptime/SLOs, frequency of on-call issues, and code coverage
• Security: Security scorecards might look at connection to vulnerability monitoring tools, test coverage, code coverage, and ticket count
• Onboarding/ Deployment Readiness: Onboarding scorecards might look at things like connection to monitoring tooling, number of reviewers in git, and runbooks attached.‍
• Migration: Migration scorecards can take many forms. From system migration to tool or framework migration. In these cases you’d look for indicators of the move, like “connected to new-CI/CD-tool” or “presence of HELM charts” after a K8s migration.‍
• Cost Optimization: This scorecard can get pretty interesting—you can bring in internal data on software costs to ensure appropriate prioritization or resource allocation, or get a bit more granular, and check for things like memory requested vs used to cut down on cloud compute costs.

Driving progress against scorecards

Scorecards are meant to be an active and ongoing analysis of your software health, but acting on that information is a different story. Internal Developer Portals should have a mechanism for alerting, and driving progress against long-term initiatives, short-term projects, or parts of longer initiatives that require more immediate attention.

Cortex provides the Initiatives feature to ensure progress against scorecards. Initiatives ensure tasks are clear, owners are aware, and deadlines are met.

Developer Self-Service

While developers derive significant value from others parts of an IDP like catalogs, on-call management, alerting, and scorecards, self-service is still the #1 most requested feature for developers to consider IDP adoption. Self-service, in this context is defined by the ability of individual developers to bootstrap new software according to best practice, without facing lengthy approval queues or a stream of back-and-forth checks with the operations team. Two major components of self-service are project generation (scaffolding), and deployment actions.

Project Generation/ Scaffolding

Internal developer portals should include the ability to quickly spin up new projects according to best practice and standards you define, and then ensure those services are appropriately catalogued. Scaffolding tools like Cortex’s provide guardrails via templates and boilerplate code. This reduces opportunity for error, ensures consistency, and cuts code for developers.

Deployment Actions

After scaffolding new software it’s important the IDP offer a way to also move that work into production. Cortex Workflows enable users to send payloads and chain together multiple actions out of the platform for execution elsewhere, including the ability to provision new resources. Where some Internal Developer Portals begin to hit their limits is in advanced orchestration that involves a chain of actions outside the platform. This competency is typically more aligned with Internal Developer Platforms, which have emerged in recent years to focus more on the later stages of the software development lifecycle.

What are the top use cases for an internal developer portal?

Internal Developer Portals are still a relatively new technology, and many use cases are still being uncovered. Here are the top six we’ve seen to date:

Drive software ownership

Ownership can be difficult to maintain without IDPs to simultaneously track context like components, dependencies, and IDPs ensure every software entity (service, infra, API, etc) has an owner, and a rotating list of someone on-call to support it. Without a proper way to track ownership, incident management, onboarding, developer productivity, and resource allocation are all negatively affected.

Ensure production readiness

‍We often hear that growing organizations start to become fractured in how they build and launch new software. Standards aren’t aligned, or are rarely even followed at all. IDPs help ensure all standards for production are met prior to launch.

Drive cost efficiency

As entropy creeps into software development practices across growing organizations, there can be wide fluctuations in the real cost of production, maintenance, and support for various software groupings and product lines. IDPs that provide custom data ingestion, flexibility in Scorecard rubrics, and UI plugins enable users to monitor for anything from the cost of resolution time, to excess in resource allocation which can help trim cloud costs.

Accelerate a migration

When it’s time to off-board a solution, migrate a framework, or upgrade a software version, getting everyone on the engineering team to respond in a timely fashion is usually extremely challenging without a dedicated program manager to follow-up individually with tasks, context, and deadlines. Internal Developer Portals that have initiative-based capabilities can ensure only appropriate resources are targeted for alerts, and deadlines are always met.

Ensure security and compliance:

Internal Developer Portals are most powerful when they act as a central platform for all of your production standards—not just those related to tickets and PRs. Connect security tooling to ensure appropriate security monitoring, code coverage, vulnerability response time, and more. Use querying capabilities to quickly identify vulnerable versions of software in use across any software component, anywhere in your ecosystem. Target owners for immediate action.

Improve developer productivity

‍Many companies today are searching for ways to deliver a high-quality developer experience to their teams. This is because a better developer experience leads to increased engagement and velocity. IDPs act as a single source of truth across all of your SDLC software to reduce context-switching for developers, and ensures they’re aligned with managers on priorities, next steps, and timelines. IDPs also unify the software production lifecycle from scaffolding new software to cataloging, updating, and improving it. Additionally, IDPs can incorporate tasks like API management, documenting services, running actions on them, deploying pieces of software, and rolling them back if needed—any and every step you consider to be critical in your development process.

Reduce onboarding friction

Software development is a complex process, especially when it involves architecting a variety of software and assembling them to build an application. With the assortment of tools put to use to develop software today, the development lifecycle is more or less scattered across these tools. As a result, the developer experience is fragmented and discordant. Internal Developer Portals pulls everything into a single place to give onboarding developers a single, unified, high-quality software development experience. They can continue to use the tools they prefer and follow certain best practices without having to worry about integrations or difficulties in communication with fellow team members or engineering leadership.

What’s the first step in onboarding an Internal Developer Portal?

Because of the variety of IDP use cases available, it can be confusing to decide where in the feature set of an IDP you should begin focusing your efforts. Cortex developed the IDP maturity curve to help users think through that same onboarding journey, regardless of whether they opt for Cortex, choose an alternative solution, or even consider building their own.

1. Aggregate: The first step to accelerating developer productivity is enabling immediate access to reliable, up-to-date information about the software they use every day. This software cataloging step is the most critical, but shouldn’t be the most time-consuming unless your IDP requires you manually model or sync data from across your ecosystem.
2. Assess: Once you’ve collected and categorized your software, it’s time to think critically about their health. In order to drive standards, you’ll need to first decide what your minimum requirements are, and what excellent looks like. This step is especially useful ahead of moving into scaffolding, which will require you to templatize those standards.
3. Prescribe: Assessing the current state of your services is an important step towards service maturity. But as your team scales, use cases expand, and projects are added, you’ll need a way to drive alignment while removing any confusion about what to do next. Initiatives allow you to carve off portions of Scorecards to drive progress to goals with steps and timelines.
4. Enable: One of the final steps in a progression towards engineering efficiency is a repeatable and reliable method for creating new software according to best practice. When tackled after setting standards of excellence, this phase results in DRYer code, speedier deployments, greater reliability, and a decreased rate of incident.
5. Optimize: To promote a culture of continuous improvement amongst developers, it’s important to provide—in kind—a platform that continually evolves to meet their evolving requirements. IDPs that provide UI customization and plugins for data embeds will improve adoption as you scale.

What’s next for IDPs

We predict the IDP space will continue to expand dramatically over the next 5 years, with standalone tools offering more features for improving developer experience and workflows, and IDP-as-a-feature becoming an increasingly popular option for DevOps and Observability venodors that appreciate the need for a central system of record.

We also expect to see greater maturity and automation in newer use cases like cost optimization and framework migration. If you have a use case you'd like to explore with Cortex, schedule time to meet with us today.