Blog
/
/
What is a developer portal and why do you need It?
Platform Engineering

What is a developer portal and why do you need It?

Zohar Einy
Zohar Einy
Aug 16, 2022
Sign up
Download PDF
Platform Engineering
Example H2
Example H3

Introduction

‍

If you've heard the term 'Developer Portal' a few times and wonder what all the fuss is about, this article is for you. Zohar Einy, CEO of Port, is on hand to run through everything you need to know about Internal Developer Portals

‍

Is devops dead?

‍As DevOps matures and becomes more complex, in software as in infrastructure, developers require easy access to an ever-increasing number of moving parts. Microservices, DevTools, CI, CD, Scripts, Saas, Cloud resources, IaC - this ever growing list and the many tools just listed in CNCF promise a huge cognitive load. Almost everyone in the industry agrees that this cognitive load is reducing developer productivity. 

Answering the question “what is deployed where” and the potential relations and dependencies that are explicit and implicit is becoming more difficult. 

From the devops point of view, serving developers has become too complex and overly reliant on “Ticket Ops”.

  • Developers flood devops with multiple tickets for one overall activity - for instance, scaffolding a microservice
  • Devops automations still require developers to make choices and increase the cognitive load as well as the chances of an error; gitops approaches work only partially
  • Temporary environments stay on forever and become orphaned
  • It becomes nearly impossible to track migrations, versions and perform audits.

‍

The rise of platform engineering

The solution to these problems isn’t to announce that devops is dead (it isn’t). The solution lies in taking a platform engineering approach, with an internal developer portal at its center.

Platform engineering is the practice of building and maintaining processes and systems that support the development, deployment, and operation of software applications. This includes the tools, processes, and procedures that enable developers to build, test, deploy, and manage the software they build. The core is creating reusable tools and automated self-service actions for developers, that provide for a better developer experience, since actions can be done seamlessly within the development process and better comply with policies, compliance and requirements from the platform side.

Platform engineering is closely related to DevOps, which is the practice of building and maintaining a culture of collaboration between software developers and IT operations professionals. At the center of platform engineering lies the internal developer portal. 

‍

{{cta_8}}

‍

What is a Developer Portal?

A developer portal is the response to the increasing complexity of software architectures. The developer portal is an operating platform that lies between the developers-users and the platforms they need. 

Developer-users can access the underlying systems through a product-like interface that is only loosely coupled with the underlying devops tools. Using this interface they can perform developer self-service actions such as spinning up new environments, requesting permissions, storing secrets, scaffolding microservices, performing day 3 operations and more. 

At the center of the developer portal lies the software catalog which shows services, environments, clouds, devtools and more, creating an in-context understanding of what is deployed where.

In short, the developer platform is a systematically organized set of interfaces that are created to make the consumption of devops assets simple and easy for developers. This creates a smooth self-service developer experience that allows developer productivity that is freed from the need to stop and figure out what to do with regards to devops assets, which suddenly become accessible. 

‍

Why Do You Need a Developer Portal?

Working with a developer portal improves many different aspects of your organization:

  • One platform - concentrating the organization's assets and tasks in one place provides an end-to-end experience for developers, thus helping all involved parties to stay on the same page throughout development; imagine a world where the developer only has one tab on their browser - the developer portal
  • One experience - instead of many devops tools and automations, yaml files and gitops, the developer accesses one place in which all actions have a similar product-like experience. Guardrails are set inside the self-service interface and everything is abstracted away. 
  • One source of truth for software and resources - at the heart of the developer portal lies the software catalog, which lists all software, clouds, environments and more, and is continuously updated. As a result, there is one source of truth answering the question “what is deployed where” and one place for reference as to the current state of services and the infrastructure they are deployed on.
  • One central repository for devops - the previous point means that devops too can use the developer portal as their central record of everything - and the fact that it is loosely coupled with the underlying devops automations means changes to those automations can be made simply and easily. This central repository can be used for audits, reporting and scorecards for developer and devops metrics, as well as service and infrastructure health. It is also one central place in which role-based access control can be defined and managed.
  • Documentation - a developer portal automatically documents all performed actions, thus keeping all company records in an orderly fashion for easy future review;‍ additionally, it also serves as one place for all APIs, acting as an API catalog

How to Create A Developer Portal for your Team? To backstage or not to backstage?

A lot of the momentum behind the interest in platform engineering and internal developer portals comes from Spotify’s backstage io project. Initially, backstage was a project designed to bring order to engineering infrastructure through the use of an internal developer portal that provides access to devops tools, data, microservices, APIs and more. In 2020 Backstage was released under an open source license, and in 2022 it was accepted as an incubating project into the Cloud Native Computing foundation. 

At the end of 2022, backstage.io announced that it will be offering five premium paid plugins, one for role-based access control to the internal developer platform, and others for user insights (analytics on backstage use) as well as “soundcheck” for KPI scorecards on developer portal entities and more.

After opting in to the idea of an internal developer portal, one of the first decisions is, as a result, whether to backstage or not to backstage. 

Aside from the ordinary considerations of whether or not to use open source technologies, the arguments against using backstage belong on two main axes:

  • Cost of coding: like all open source projects, backstage requires coding, which may be the opposite of freeing devops to do innovation projects, which may have been the objective of going after a developer portal project in the first place. 
  • Cost of product management/UX: improving the developer experience requires taking a product approach, meaning that the developer portal presents developers with a user interface that makes developer self-service actions simple to execute, free of cognitive load with guardrails inside. This requires UI resources; similarly, understanding the needs of developers and prioritizing them also requires a product-manager-like persona in the developer experience or platform engineering team.

‍

As a result of these factors, companies may decide to buy a product that builds an internal developer portal or use an in-house solution.

‍

Who Interacts With a Developer Portal?

Developer portals are not only for developers or devops. In fact, additional roles can benefit from the ecosystem the portal creates. 

  • Customer success or other operational roles - can use the developer portal to make simple actions such as provisioning a customer environment or permissions that otherwise required a special request to devops.
  • Engineering Managers - use the developer portal and its insights to better ask ad hoc questions and receive reports about service health, migration and security statuses, controlling cloud costs and KPIs such as DORA metrics;
  • NOC - use the understand assets that are affected by security incidents. For example, being able to track affected k8s clusters by the log4j open source vulnerability;‍
  • CI/CD pipelines - ue the developer portal to fetching data from the Software Catalog to make real-time automated decisions such as deploying a service if it passed a maturity test (operations, security, etc.) or other thresholds.

‍

Components of a Developer Portal

The developer portal is essentially made of two parts:

  • The developer self-service actions elements - the product like experience that curates a well-designed experience for developers
  • The software catalog - which provides a central source of truth and API catalog for the use of developers and devops.

‍

Developer Portal Best Practices: The Software Catalog 

The Software Catalog Layer is where developers go to discover the answer to any software question they might have. It's a unified view of the different software components within the organization. 

Software components you might find in the software catalog layer often include:

  • Microservices;
  • Cloud Resources (K8S, Lambda, RDS, etc…);
  • Cloud Providers (AWS, GCP, Azure);
  • Environments (Production, Staging, QA, Security, DevEnvs…);
  • Permissions;
  • Secrets;
  • Deployments.

‍

And that's just the beginning. The many components can also have dependencies between them. 

A good software catalog design is important - not to divorce services from infra or just serve as a kubernetes abstraction. What’s a good design for a software catalog? It catalogs all the elements associated with the software - the microservices, the resources they are deployed on, each specific deployment and the dependencies between any and all of them. The software catalog is a graph of metadata, showing dependencies and visualizing it all so that it’s easy to keep track of components, ownerships and the software development lifecycle.

‍

Developer Portal Best Practices: Developer Self-Service Actions Layer

Once you have organized your software components, the self-service layer is where developers use a product-like interface to do whatever they need, with the proper guardrails and policies.

Excelling at developer self-service is the core of success in a developer portal. It brings a consistent and repeatable process for developer actions and removes error-prone work. The user experience should be comparable to the use of any other software product with a clear next best action at any moment. While many developer portals focus on microservice scaffolding it is important to aspire for more - to let developers act beyond microservices, letting them provision, terminate and perform day 2 operations on any entity within the software catalog (provided it is allowed by the role-based access control settings), as well as creating temporary dev environments, getting permissions for an S3 bucket or being able to add a secret to a microservice. 

‍

{{cta_7}}

‍

Control Layer

With a great developer portal comes great responsibility. Without proper controls in place to cover security, compliance, and cost, the developer portal can create chaos. 

It's possible to implement a number of control measures across the Software Catalog and developer Self Service layers. 

  • Permissions: manage access to the data shown in the Software Catalog for viewing;
  • Actions: allow different self-service actions based on a role within the organization and limiting the amount and duration of such actions;
  • Logging: all actions within the developer portal  are tracked to ensure you stay compliance;
  • Automation: revoke, remediate, revert, and cron-job automations will help set proper processes around developer portal actions. 

‍

Product Management Layer

This just might be my favorite layer. When designing a developer portal. You need to think like a Product Manager. One that actually understands the user personas - the developers. Here are a few things to include if your developer portal is going to be successfully adopted:

  1. Wizards and tutorials for new users;
  2. Embedded documentation to explain the developer portal glossary;
  3. Custom views for different teams depending on their business function;
  4. Chat and support functions are easily accessible at all times;
  5. Analytics dashboards to learn the strengths and weaknesses of the developer portal
  6. Scorecards to track KPIs for entities, services, teams, developers and devops.

‍

Stakeholders in a Developer Portal

Developer Portals are unusual in that they are used as internal products. The 'customers' are colleagues of the team that adopt it. 

The team often responsible for the developer portal could be the:

  • DevEx team;
  • Platform team;
  • DevOps team.

‍

These teams are responsible for the success of the developer . Making it successful means selling their colleagues on the new platform. Encouraging colleagues to adopt new ways of working can be challenging – they have to see the benefits in the short term and the long term. 

Developer Portal customers' can be:

  • Developers;
  • DevOps;
  • NOC;
  • SRE;
  • Data Engineers;
  • Customer Success.

‍

Each one has a unique set of needs. Therefore, it's essential to design the developer portal with each group of users in mind to see the platform's immediate benefit.

A recommended book for thinking about developer portals is Team Topologies, talking about the NG architecture of R&D teams when thinking about IDPs (Internal Developer Portal).

‍

Benefits of a Developer Portal

Hopefully, you can see why Developer Portals are becoming an integral part of an effective tech stack. Forward-looking companies like Spotify and Lyft have already implemented and advocated for developer portals. They will soon become a standard feature in more and more organizations. 

However, if you need a few short, snappy sentences to sell this concept to your manager - we've got you covered:

‍

Take the Developer Experience to peak performance

R&D is one of the most strategic units within any company. Ensure developers can easily navigate through the software stack, and you'll allow them to reach peak agility and performance.

‍

Eliminate infrastructure clutter. Deliver faster

Save valuable time spent understanding, communicating, and managing the different assets R&D rely on. Remove the clutter, chaos, and ownership headaches around microservices, cloud resources, and databases. Time-consuming and complex tasks become one-click operations allowing the team to get results faster.

‍

Lower operating costs

Being more organized means lowering costs. A unified, self-service interface allows teams to efficiently classify and manage costs. Break down resource consumption by each team to make better decisions and optimize costs.

‍

Reduce technical debt

Technology is here to change, and it's time to become futureproof. The DevPortal's user interface is decoupled from the underlying infrastructure. This means that the constant updates and changes made 'under the hood' don't impact the user interface - internal customers get a consistent experience. 

‍

Conclusion

The Developer Portal is becoming an essential part of every R&D tech stack. When designing yours, work your way through the various layers, considering how they will work together. Stay agile, don't over-complicate it, and you'll be ok!

At Port, we are passionate about Developer Portals. Our dedicated team of expert DevEx Engineers & Product Managers are on hand to help and advise your DevPortal strategy.

‍

Updated December 22

{{cta-demo}}

Book a demo right now to check out Port's developer portal yourself

Book a demo
{{jenkins}}

It's a Trap - Jenkins as Self service UI

Read more
{{gitops}}

How do GitOps affect developer experience?

Read more
{{ebook}}

It's a Trap - Jenkins as Self service UI. Click her to download the eBook

Download eBook
{{cyberark}}

Learning from CyberArk - building an internal developer platform in-house

Read more
{{dropdown}}

Example JSON block

{
  "foo": "bar"
}

Order Domain

{
  "properties": {},
  "relations": {},
  "title": "Orders",
  "identifier": "Orders"
}

Cart System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Cart",
  "title": "Cart"
}

Products System

{
  "properties": {},
  "relations": {
    "domain": "Orders"
  },
  "identifier": "Products",
  "title": "Products"
}

Cart Resource

{
  "properties": {
    "type": "postgress"
  },
  "relations": {},
  "icon": "GPU",
  "title": "Cart SQL database",
  "identifier": "cart-sql-sb"
}

Cart API

{
 "identifier": "CartAPI",
 "title": "Cart API",
 "blueprint": "API",
 "properties": {
   "type": "Open API"
 },
 "relations": {
   "provider": "CartService"
 },
 "icon": "Link"
}

Core Kafka Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Kafka Library",
  "identifier": "CoreKafkaLibrary"
}

Core Payment Library

{
  "properties": {
    "type": "library"
  },
  "relations": {
    "system": "Cart"
  },
  "title": "Core Payment Library",
  "identifier": "CorePaymentLibrary"
}

Cart Service JSON

{
 "identifier": "CartService",
 "title": "Cart Service",
 "blueprint": "Component",
 "properties": {
   "type": "service"
 },
 "relations": {
   "system": "Cart",
   "resources": [
     "cart-sql-sb"
   ],
   "consumesApi": [],
   "components": [
     "CorePaymentLibrary",
     "CoreKafkaLibrary"
   ]
 },
 "icon": "Cloud"
}

Products Service JSON

{
  "identifier": "ProductsService",
  "title": "Products Service",
  "blueprint": "Component",
  "properties": {
    "type": "service"
  },
  "relations": {
    "system": "Products",
    "consumesApi": [
      "CartAPI"
    ],
    "components": []
  }
}

Component Blueprint

{
 "identifier": "Component",
 "title": "Component",
 "icon": "Cloud",
 "schema": {
   "properties": {
     "type": {
       "enum": [
         "service",
         "library"
       ],
       "icon": "Docs",
       "type": "string",
       "enumColors": {
         "service": "blue",
         "library": "green"
       }
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "system": {
     "target": "System",
     "required": false,
     "many": false
   },
   "resources": {
     "target": "Resource",
     "required": false,
     "many": true
   },
   "consumesApi": {
     "target": "API",
     "required": false,
     "many": true
   },
   "components": {
     "target": "Component",
     "required": false,
     "many": true
   },
   "providesApi": {
     "target": "API",
     "required": false,
     "many": false
   }
 }
}

Resource Blueprint

{
 “identifier”: “Resource”,
 “title”: “Resource”,
 “icon”: “DevopsTool”,
 “schema”: {
   “properties”: {
     “type”: {
       “enum”: [
         “postgress”,
         “kafka-topic”,
         “rabbit-queue”,
         “s3-bucket”
       ],
       “icon”: “Docs”,
       “type”: “string”
     }
   },
   “required”: []
 },
 “mirrorProperties”: {},
 “formulaProperties”: {},
 “calculationProperties”: {},
 “relations”: {}
}

API Blueprint

{
 "identifier": "API",
 "title": "API",
 "icon": "Link",
 "schema": {
   "properties": {
     "type": {
       "type": "string",
       "enum": [
         "Open API",
         "grpc"
       ]
     }
   },
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "provider": {
     "target": "Component",
     "required": true,
     "many": false
   }
 }
}

Domain Blueprint

{
 "identifier": "Domain",
 "title": "Domain",
 "icon": "Server",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {}
}

System Blueprint

{
 "identifier": "System",
 "title": "System",
 "icon": "DevopsTool",
 "schema": {
   "properties": {},
   "required": []
 },
 "mirrorProperties": {},
 "formulaProperties": {},
 "calculationProperties": {},
 "relations": {
   "domain": {
     "target": "Domain",
     "required": true,
     "many": false
   }
 }
}
{{tabel-1}}

Microservices SDLC

  • Scaffold a new microservice

  • Deploy (canary or blue-green)

  • Feature flagging

  • Revert

  • Lock deployments

  • Add Secret

  • Force merge pull request (skip tests on crises)

  • Add environment variable to service

  • Add IaC to the service

  • Upgrade package version

Development environments

  • Spin up a developer environment for 5 days

  • ETL mock data to environment

  • Invite developer to the environment

  • Extend TTL by 3 days

Cloud resources

  • Provision a cloud resource

  • Modify a cloud resource

  • Get permissions to access cloud resource

SRE actions

  • Update pod count

  • Update auto-scaling group

  • Execute incident response runbook automation

Data Engineering

  • Add / Remove / Update Column to table

  • Run Airflow DAG

  • Duplicate table

Backoffice

  • Change customer configuration

  • Update customer software version

  • Upgrade - Downgrade plan tier

  • Create - Delete customer

Machine learning actions

  • Train model

  • Pre-process dataset

  • Deploy

  • A/B testing traffic route

  • Revert

  • Spin up remote Jupyter notebook

{{tabel-2}}

Engineering tools

  • Observability

  • Tasks management

  • CI/CD

  • On-Call management

  • Troubleshooting tools

  • DevSecOps

  • Runbooks

Infrastructure

  • Cloud Resources

  • K8S

  • Containers & Serverless

  • IaC

  • Databases

  • Environments

  • Regions

Software and more

  • Microservices

  • Docker Images

  • Docs

  • APIs

  • 3rd parties

  • Runbooks

  • Cron jobs

Check out Port's pre-populated demo and see what it's all about.

Check live demo

No email required

Contact sales for a technical product walkthrough

Let’s start

Open a free Port account. No credit card required

Let’s start

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start

Check out Port's pre-populated demo and see what it's all about.

(no email required)

Let’s start

Contact sales for a technical product walkthrough

Let’s start

Open a free Port account. No credit card required

Let’s start

Watch Port live coding videos - setting up an internal developer portal & platform

Let’s start

Let us walk you through the platform and catalog the assets of your choice.

I’m ready, let’s start