Production Readiness
Best Practice

The CTO Pocket Guide to Internal Developer Portals

Internal Developer Portals have quickly become a baseline requirement for scaling engineering teams that want to accelerate onboarding, improve software health, and increase developer autonomy and productivity. Find all you need to know in our latest CTO pocket guide.

By
Lauren Craigie
-
June 5, 2024

The engineering macro-climate is in crisis. Market dynamics have put increased pressure on teams to ship faster in order to stay competitive, while budgets are under significant scrutiny. At the same time, the advent of new tools and architectures promising high-velocity, collaborative development increasingly lack the implementation structure needed to preserve their benefits. 

As a result, onboarding is stalling out, incidents are up, and deployments are down.

It’s no wonder then that Gartner has reported a 325% increase in inquiries regarding developer productivity. If devs have “all they need” to go fast, why is the opposite more true than ever? 

Tooling isn’t the problem—it’s the lack of connection between them. Without up-to-date visibility across the entire engineering ecosystem, wrapped in a model for safe developer self-service, it’s impossible for devs to build according to best practice, ship quickly, or keep tabs on software they own. Enter: Internal Developer Portals (IDPs). In this guide, we’ll explain what IDPs are, step through some use cases and benefits, and outline top implementation options.

What are IDPs, and how can they help?

Internal Developer Portals (IDPs) are the new connective tissue of an engineering organization. Many have historical roots as service catalogs prior to 2018, which enabled them to quickly expand use cases thereafter. Where ITSMs, APM, ticketing, and code review tools leave off, IDPs begin—not replacing, but finally connecting all tools, documentation, and team details in one central system of record purpose built for distributed teams and architectures. 

Now it’s possible to not only see where uptime is lagging, but also who owns that each piece of software, when it was last updated, what packages it’s running, what code scanners it’s connected to, how many open tickets it has, what the dependencies are, what needs to be done to get back into alignment, how to build something similar, and more, all from one platform.

IDPs are purpose built to alleviate pain from the new problems of scale faced by growing engineering teams, and as such, can be counted on to serve three critical functions:

  • Single source of truth. An IDP integrates with, connects across, and allows for unified querying of all of the engineering teams’ data sources, including IT, infrastructure, source control, service definitions, APIs, workforce management, and in the case of IDPs that offer custom data and a plugin framework—data from any internally developed tools.
  • Quality standards enforcer. An IDP supports reporting on and enforcement of standards of excellence—be they short term initiatives like software migrations or long-term programs like resource optimization and service maturity. With an IDP, standards are centralized, monitoring is continuous, and action is obvious.
  • Engineering accelerator. With always-up-to-date information about their ecosystem, engineers can onboard faster, reduce incident response time, and increase velocity. IDPs that enable true self-service can also automate or obviate parts of production like templating new software, requesting permissions, or waiting on approvals.  

Where IDPs make the biggest difference

Because IDPs are essentially the bedrock of your engineering information architecture, top use cases involve moments where finding the right information, quickly, is paramount. Here are some examples:

Accelerate developer onboarding

Drastically reduce the time developers need to gain context about the software they’re responsible for—even if they’re inheriting components from folks who have moved off the team or left the organization. No more piecing together information from across the ecosystem when everything they need can be found in their catalog. If your IDP automates onboarding protocol, devs can skip request and approval queues and begin work immediately.

Accelerate migrations and acquisitions

Teams are always moving from one product, framework, or package to another. End-of-life initiatives, cloud migrations, new teams, new programs—the list of catalysts is endless. But getting everyone to migrate on time isn’t easy. Standups, emails, Slack messages—all get lost in the noise of everyday operations. IDPs that come with a comprehensive notification system can automate querying for the presence of outdated tools/packages, trigger targeted alerts, and provide comprehensive trend reports.

Set standards for quality and velocity

Because IDPs connect all your data, it’s easy to create standards that span multiple tools and teams. Build a security scorecard that ensures critical vulnerabilities are addressed promptly, while code coverage stays at an acceptable range. Build a PHP or Java language best practice scorecard that only applies to certain applications. Or combine these in a production readiness scorecard that spans language, security, observability, efficiency, and any other best practice. IDPs that provide complete source and structure flexibility mean any scorecard is possible.

Track progress to goals

Engineering teams often have ticketing or project management software to ensure progress against particular milestones. However, project management software requires self-reporting, which can be a drain on developer productivity. Internal Developer Portals let you to create short or longterm projects pertaining to the state or quality of software in your catalogs, automatically scan for progress to goals, and alert appropriate owners of action required at designated intervals. Managers can then track progress by component, team, product group, and more. Immediately see which team updated to the latest code scanner. Which product line hasn’t migrated off that old package. Or who isn’t hitting deployment frequency goals.

Measurably improve developer productivity

Productivity can be a tricky topic—often qualitative in nature, metrics alone never really tell the whole story. So stand-alone engineering intelligence solutions that don’t pair software health with team health can have limited value. However, if your Internal Developer Portal has built-in engineering intelligence to surface trends in things like deployment frequency, PR review rate, or change failure rate, you can use this data as a lagging indicator of areas further left in the software development lifecycle that require your attention. Observe where your team is at, and then prescribe informed goals for all or each depending on what else they have on their plate.

Optimize build and maintenance costs

While storage and compute is much cheaper than it was 10 years ago, usage-based pricing from cloud providers can still sting at scale, accruing to millions in annual spend. Of course, it’s often possible to optimize how software is built—small changes can add up to significant savings. If your IDP can read memory allocation data, for example, it’s possible to create a scorecard that checks for over-allocation of memory at startup. Set a goal range to cut excess, and alert owners of changes needed when services they own are in breach.

Reduce overhead in bootstrapping new software

Many IDPs provide templating capabilities that make it easy to ensure devs can quickly build new components according to standards you define. Ensure consistent naming conventions, require descriptions, dependency mappings, on-call assignments, and more. Cut rote work with boilerplate code that reduces overhead when building common components like React app or Spring boot service. Then deploy to a specified environment, provision a resource, or take any other custom action to integrate your new creation.

Ensure ongoing production readiness

According to a recent study, no two organizations reported the same production readiness workflow, with 66% struggling to align on standards, and the majority failing to apply continuous monitoring post deployment. IDPs mean production readiness doesn’t need to end at deployment. Ensure software stays aligned with best practice, no more how complicated your standards or organizational structure. For example, ensure SLAs are met, and runbooks are attached once software has been observed in the wild for more than 30 days. Monitor, track, and support progress on retrofitting older components to new production readiness standards. 

Automate access and provisioning

All IDPs should enable some scaffolding capabilities. Some will even allow you to send a payload off platform to execute work in adjacent tools like deploying a service or filing a security ticket via HTTP call. But the best will go one step further to allow you to chain multiple actions like data transformations, user inputs, and manual approvals. The latter allows for truly comprehensive onboarding, deployment, and incident management workflows. No more, “can I get access to this?”

Enforce and Monitor Security and Reliability Metrics

Bridge the gap with security by supporting all security and reliability software requirements in one place. Require SLOs to be defined, maintained, and observed, as appropriate for each service, team, or line of business. Ensure connection vulnerability scanners and code coverage tools. And use advanced reporting to aggregate status for core metrics once spread across multiple tools like latency, error, traffic, saturation, test failure, tickets, vulnerabilities, and more. Build a culture of reliability and ownership

Cut time-to-find during incidents

As a single source of truth, an IDP also supports faster and more efficient incident response. Democratized information access and central service ownership catalogs means that the correct owner for a service or product is contacted in case of an outage, appropriate documentation and history logs are surfaced, and runbooks are provided. This reduces mean-time to respond or repair (MTTR) without requiring devs to spend time on disparate system archaeology.

Top Internal Developer Portal Options

IDP went from “You mean Identity Provider?” to mission critical asset in about 18 months. Understandably so, given the rapid rate of microservice adoption necessitating their existence. If you’re looking for a solution to provide a central system of record, continuous standards, and developer self-service, there are a few categories to consider:

Build your own

Homegrown

Large organizations looking to reduce friction in development may begin to collect internally developed point solutions that help with things like onboarding, cataloging, information discovery, and permissions allocation. In our experience, these solutions can be effective with consistent championship, clear cross-company integration strategies, dedicated built and support functions, and high tolerance for often sporadic or low developer adoption. Of course, high cost of ownership and maintenance comes with all internal developed solutions, 

Backstage

An open source platform for building developer portals, Backstage has been a popular project for developers to begin experimenting with as they think through how to approach cataloging and productivity initiatives. As an open source solution, Backstage offers unlimited flexibility for building your IDP. However, recent critiques include high operational overhead at setup and while maintaining, high cost of building and testing community integrations, poor alignment across teams experimenting with their own instance, severe lack of developer adoption, and over-reliance on an increasingly divergent version of React. 

IDP as a feature

Atlassian

Atlassian’s Compass is a lightweight internal developer portal which may be a good starter solution for organizations that are heavy Atlassian users. Critics of Compass point to lack of integration with non-git or Atlassian based tools, lack of awareness of identity provider data for ownership information, little customization in standards creation, and lack of automation in key areas like entity mapping, catalog hydration, standards monitoring, task alerting, and infrastructure provisioning. 

Datadog

While Datadog does not offer an Internal Developer Portal, organizations with a primary use case of cataloging services and applying some lightweight static scoring may be initially drawn to Datadog’s Service Catalog offering. However, teams should be prepared for limited catalog types (services vs resources, APIs, pipelines, teams, etc), limited external integrations, inability to customize scorecards that only use live Datadog telemetry or static JSON checks, inability to connect to other observability tools, limited reporting, manual ownership tracking, no initiative alerting or tracking to drive developer action, and no self-service tools for deploying scaffolding or infrastructure (separate offering for this).

Dedicated SaaS solutions 

Port

Port is a commercial IDP suggesting greater flexibility with lower time to value than Backstage, enabling users to build their platform from building blocks, without as much overhead as an open source solution like Backstage. Port also offers a self-service model for quick experimentation—a unique offering amongst SaaS providers. 

Recent critiques of Port include the time required to build, test, and maintain components and reporting modules, and trouble aligning pockets of the org that have begun experimenting. Reliance on the Ocean framework for modeling data also requires significant up front investment to map and re-map information architectures when you want to add new data. There is no plugin framework to easily visualize/replicate data experiences from across the stack. Port is also not offered on-prem, which may be a deciding factor for legacy or regulated businesses

OpsLevel

OpsLevel is a commercial IDP that offers most functionality out of the box—not requiring users to build any components themselves. While OpsLevel may afford faster time to value than Backstage or Port, the tradeoff may be limited ability to customize. A rigid data model restricts the types of content you can import, catalog structures you can create, and scorecard rubrics you can manipulate—requiring you to treat all entities as “services" or “teams.”

OpsLevel’s integrations are also just web-hooks for tools like GitLab and Jenkins which means you’ll do a fair bit more work to get your entire ecosystem of tools connected to push rather than just pull data, and there is no plugin framework to visualize additional data sources or create custom experiences for developers. OpsLevel also doesn’t provide any reporting relating to productivity or performance by team or individual, which means software health might only be half the story. Slack integrations are “pull” only, requiring users to ask questions of the integration to get necessary information.

Cortex

Cortex is a commercial IDP that intentionally strikes a balance between the “must build everything” and “can’t customize anything” dichotomy that’s emerged in market today. With custom catalog, scorecards, and workflows, plus a plugin framework, support for custom data, and 50+ company-built and backed integrations, Cortex offers faster ramp while preserving the ability to tailor your solution as needed. 

Targeted out-of-platform email and messenger alerts and the ability to collect data from, or ask questions of your Cortex messenger bot has also enabled higher rates of adoption and alignment without disrupting the way developers prefer to work. Similarly, Cotex is the only IDP to offer chained actions, freeing developers from the request and permissioning queue associated with developer onboarding and infrastructure provisioning. 

These developer-focused features also continue to greater developer productivity, which can be measured in Cortex via the Engineering Intelligence module which can be used to track the impact of software health on things like deploy frequency and PR rate of review. Additionally, Cortex offers options for cloud-hosting or on-prem deployments with dedicated customer success support, making it a popular choice for enterprise organizations including Adobe, Workday, and Xero.

Adoption paths and immediate benefits

With some careful planning, adopting an IDP can provide immediate uplift, with long-term incremental value. 

A typical implementation process will move through the five stages of the maturity curve above, and positively impact developer productivity throughout. While it’s likely that you may feel more urgency in one part of this process than another, optimum benefit is based on compounding value of each subsequent stage. Quick wins are always possible, but to avoid revisiting foundations, we do recommend this general path:

  1. During Aggregate, developers will learn where current work sits, avoid an increase in duplication and speed-up resource use.
  2. Assess will help surface operational needs and start to highlight what excellence looks like, improving focus and prioritization for engineering work. 
  3. Prescribe leverages scorecards to increase compliance, support gamified approaches to standard adoption and see economies of scale as standards spread across the org.
  4. Enable sees templated and reliably repeatable processes in place for creating new services, and other work, resulting in faster deployments, DRYer code, and lower incident rates.
  5. Optimize is a final stage of continuous, incremental improvement, as various metrics are refined, accumulated data allows for more fine grained improvements, and the platform evolves to meet new requirements.

A deeper dive into Cortex’s Internal Developer Portal

Cortex pioneered the three requirements for Internal Developer Portals:

Centralize data and standards across all tools

Cortex was designed to facilitate maximum flexibility without excessive overhead. Fully custom catalogs, 50+ out of the box integrations, the ability to bring in custom data, and a rich plugin architecture enables teams to build new data experiences that best fit developer workflows. 

Anything that details how software is built, by whom, when, and how, can be captured by catalogs segmented by software type like services, resources, APIs, infrastructure, etc. Any standard that governs how code is written, tested, secured, reviewed, or deployed can be unified, and even re-segmented by team, type, domain, or exemption status, to ensure all components are managed in context.

Apply always-on standards for continuous alignment

Code repos, project management tools, and wikis are all indisputably useful tools for engineering teams. But none have a live view of the rest of your software ecosystem, which means none can tell you when software falls out of alignment with critical requirements for security, compliance, or efficiency.

Because Cortex is a one-stop-shop for all your data and documentation, it can also serve as a means of continuously monitoring alignment to all software standards you define in a scorecard. So if code is updated, ownership changes, new tools are adopted, or old packages hit end-of-life, Cortex makes it easy to see what needs attention.

Cortex is the only IDP that provides the level of data model flexibility to define any rule, for any data, targeting any audience. This means users can create Scorecards with rule types like:

  • Binary: Check for connection to a vulnerability scanner or use of the most up to date package
  • Target: Require at least 70% code coverage or two reviewers
  • Threshold: Allow no more than one p0 vulnerability, or five open JIRA tickets per service

In order to ensure scorecards aren’t just passive assessment systems, Cortex also enables teams to drive meaningful action by:

  • Defining deadlines—so certain measures are actioned before a set date and time
  • Pushing alerts—via Slack, Teams, or email to ensure devs know what’s needed, when
  • Uploading exemption lists—to target only the folks that need to take action

Provide approved templates to ship quality code quickly

Enabling self-service is a top priority engineering leaders that care about both developer productivity, and happiness. But self-service also contributes to higher quality software, and therefore should be part of any robust production readiness process. Cortex enables teams to create pre-approved templates with health checks built in, so developers can reduce time spent looking for standards and context-switching across applications.

Don’t just build production readiness standards into templates with boilerplate code, but initiate any workflow from within the platform using a customizable HTTP request, data transformation, user input request, Slack message, and manual approval. Now developers can do things like:

  • Onboard a new developer
  • Shore up incident content quickly
  • Provision new resources
  • Make an API call to AWS
  • Deploy a service
  • Provision a resource
  • Assign a temporary access key
  • Create a JIRA ticket, or r any other action that would help the developer complete a task, or in this case, their production readiness checklist

Self-serve templates and workflows are also especially useful for onboarding new developers that would normally need time to ramp on your chosen production readiness protocol. By centralizing the tools and templates needed to align with standards, time to impact can be drastically reduced.

Conclusions

Alignment is hard, automation is key, and assessment has to be continuous. IDPs can help.

  • It acts as a single source of truth
  • Helps apply always on standards
  • and abstracts away boilerplate engineering work and code.

IDPS also integrates seamlessly with all of your existing infrastructure, data models, and business initiatives. Launch faster, improve security, speed up incident response, and make better informed data driven decisions. For more information on how Cortex might help your developer productivity or software standardization initiatives, take a tour of the product, or book a custom consultation today.

Production Readiness
Best Practice
By
Lauren Craigie
What's driving urgency for IDPs?