Backstage: all you need to know about this developer portal

What is a Developer Portal?

The Developer Portal (DevPortal) is a unified, self-service layer of the developer's ecosystem. It consolidates all the information and tools that a developer might need, usually managed by the Platform Engineering team / DevEx team.

Developer Portals take the chaotic ecosystem of moving parts - microservices, DevTools, CI, CD, Scripts, and so on - and make it easily searchable and accessible. They are essentially an abstraction layer that meets the needs of every individual developer in the organization. 

The visualization layer contains an overview of the organization's DevOps assets - services, cloud assets, environments, and more. Finally, the self-service layer is where developers go to perform actions. Everything you need to operate the entire lifecycle of DevOps assets, from provisioning to safe teardown, is concentrated here.

Together, they hold everything a developer needs to work quickly and efficiently.

‍

Why do you need a Developer Portal?

A good developer experience is hard to achieve. Even simple operations, such as connecting a cloud resource to service, requires diverse knowledge to ensure it stands at scale and avoids bugs and security vulnerabilities. To complicate matters, no two organizations will have the same toolkit.

Companies that want to sustainably and reliably improve their software speed delivery need to invest heavily in the developer experience. Creating a better environment will raise productivity levels and allow companies to attract and retain engineering talent - an increasingly difficult task.

Building a DevPortal is the best way to do this.

{{cyberark}}

‍

What is Backstage?

Backstage is an open platform for building Developer Portals that create, manage, and explore software from a single UX layer. Backstage was developed initially at Spotify as an internal tool and then open-sourced in 2020. 

Backstage allows you to develop the two layers of an effective DevPortal - the visualization layer and the self-serve CRUD operation layer. Together, they cover all of a developer’s services and underlying cloud, compute, storage, and other relevant resources.

‍

Backstage Use Cases

So which features do Backstage adopters find most useful? Text analysis of the adopters’ descriptions reveals that Service catalog, Documentation, and Software Templates are the most frequently used features. Let’s delve into that further.

‍

Backstage Main Features

Backstage gives you the building blocks to create a platform to manage your complex software development ecosystem.

Backstage’s core features currently focus on visualization: Service Catalog, TechDocs, and Kubernetes Plugin. Only the Software Template feature supports the self-service function, and that’s limited to the creation stage without second-day operations options.

(Having said that, Backstage is open-source written in TypeScript. Therefore, you can add code that will do operations upon your organization’s DevOps assets - more of this later on.)

‍

Service Catalog

The Service Catalog is possibly the most crucial element of a DevPortal. A well-maintained Service Catalog brings back a level of transparency that enterprise teams can lose with scale. Here, the developer should be able to find all relevant information about the organization’s services: owner, lifecycle, runtime, version, slack channel, last deployment link, and more.

Backstage’s Service Catalog is a unified metadata source and ownership information for all team software. You can track your services, apps, pipelines, and more in one unified view. The catalog is built around metadata YAML files, which are stored together with the application code. These are harvested and visualized in Backstage.

The Software Catalog can contain many entity types with different connections and dependencies between them. New entities and connections can also be implemented:

‍

Backstage TechDocs

Many enterprises find that much of the knowledge held by their developers is undocumented. Unfortunately, bridging these unrecorded knowledge gaps is an uphill battle and often results in snowballing challenges. For example, onboarding new engineers into complex tech stacks with hundreds of microservices and tools becomes a mammoth task.

Backstage TechDocs allows engineers to write technical documentation as Markdown files that live together with the code. “TechDocs” is Spotify’s in-house “docs like code” solution and is the most used feature in Spotify’s internal version of Backstage.

The real advantage of TechDocs is that the documentation lies in files alongside the code. Each change is managed and recorded through the Git process - last updated, contributors, code reviews, automated tests, owner, Github issues, etc. The documentation is then displayed in HTML format to be searched for and edited through Backstage’s Markdown files. 

Working this way means that both writers and developers feel ownership over the documentation - creating a culture of collaboration and teamwork.

‍

Kubernetes Plugin

Backstage’s Kubernetes plugin connects to your existing ecosystem, simplifying the deployment workflow and visualizing all deployment statuses in a single view.

The plugin helps developers get Kubernetes data from the service rather than cluster perspective. This makes the dashboard uniquely designed for the developers using Kubernetes rather than the DevOps engineers who manage the clusters. As a result, developers shouldn’t have to use cluster management skills to perform everyday tasks like checking autoscaler limits or seeing which pods are experiencing errors. 

With this plugin, there is no need to move between multiple Kubernetes dashboards to see the overall service status. No matter where the service is deployed.

Not only that, a developer will be able to see:

• The current status of their systems running in Kubernetes, including information aggregated from multiple clusters/regions
• Any errors reported by Kubernetes
• How close the system is to its autoscaling limits
• Container restarts

‍

This feature adds “run-time” data to the services managed in the Software Catalog to create end-to-end visibility. Metadata (APIs, documentation, ownership, etc.) to “run-time” metrics like CPU usage are all included.

It’s worth noting here that while this plugin has many benefits, it will not suit every organization. There will be companies that find the dashboard too abstract or too detailed. Creating a tailored view to suit your developer's individual needs with this plugin can be a challenge. If you go down this route, get ready to write some React components!

‍

Backstage Software Templates

The Software Templates plugin concentrates on the self-service element of the Developer Portal. 

There are many benefits to Software Templates. They help organizations scale company best practices (CI, Documentation, Logging, K8S configuration). Additionally, they save developers time with repeatable templates that your whole team can use. And they allow individual developers to start new projects quickly and in the "right way" without rebuilding every time.

DevOps engineers can simply define a code skeleton with variables to be filled in and push the template to GitHub, GitLab, or any Git provider. The developers can then select the relevant template and use the creation wizard to fulfill the relevant parameters. At the end of the process, a new repository with all the defined standards is created and the component is added to the catalog inside Backstage.

The downside to the Software Template feature is that it focuses only on the create operation and not the second-day operation. Creation is crucial, but most functions are performed on already-provisioned services. It is possible to support those second-day operations, but you’ll have to write a lot of custom TypeScript.

This makes the Software Template feature a great way to provision new services but less suitable for provisioning infrastructure or second-day operations like deploying services to different environments.

‍

{{cta_1}}

‍

Considerations for using Backstage Plugins

Backstage is a single-page application composed of a set of plugins. Most plugins are a stripped-back version of the complete tool. These plugins often provide an overview; the developer can go directly to the dedicated UI for more information.

Backstage attempts to combine all relevant data into a “single pane of glass” rather than being spread across independently built “islands.” As your infrastructure portfolio grows, the level of complexity will increase. A key benefit of the Backstage plugin model is that it allows you to add more tools without increasing the complexity for each individual user.

Backstage can be easily extended; the best way to do that is to use the plugins. The platform provides design guidelines to ensure the overall user experience stays consistent between plugins.

And one note of caution, make sure your team has the skills and experience to use the Backstage plugins. These React components written in Typescript are added to each service’s page. If your DevOps engineers are responsible for establishing a DevPortal, ensure they are experienced with UI development.

‍

Conclusion

Backstage is a great Developer Portal option but won’t be suitable for every organization. 

Backstage will allow you to effectively implement the visualization layer and self-service layer through a set of easy-to-use plugins. 

However, to make the Developer Portal you really want, one that will answer all your developers' specific needs, you will have to write a lot of React code. If your DevOps engineers don’t have the skillsets and experience to develop UI components quickly, you’ll walk straight into time-consuming challenges.

Ultimately, a Developer Portal is a product, and the developers are the customers. When developing such a complex product, having an experienced team to oversee things is crucial. If you have a dedicated team of DevOps Engineers, Senior Full-Stack engineers, and a product owner, then Backstage is an excellent option for you.

{{cta}}