Spotify's Backstage: A Simple Introductory Guide
What is Spotify's Backstage? Why did Spotify build it, and how can it help you? Is it the right solution for your team? We have the answers.
Spotify's Backstage is a recent addition to the developer portal community. It has a lot to offer a large engineering organization that needs a way to organize its internal tools and documentation. But is it the right portal for you? What are the pros and cons of Backstage's developer portal offering?
Let's look at Backstage's features, what it takes to run it, and how you can decide if it's your best option for an engineering home base.
Backstage is a platform for creating developer portals. It gives you the tools you need to create a single place to keep your engineering team's documentation, tools, and other critical resources.
You can use Backstage to:
Backstage is an open-source offering that you need to download, install, and maintain yourself. Spotify donated it to the Cloud Native Computing Foundation (CNCF) and licensed it under the Apache 2.0 license, so it's free to use for commercial or personal purposes.
Plugins are what drive Spotify's Backstage functionality. They offer a variety of features and integrations. While there are more than 130 plugins available, three of them provide the portal's core offerings: the Software Catalog, Software templates, and Techdocs. Let's take a brief look at each one.
Backstage has a software catalog that acts as a centralized location for tracking internal applications, libraries, pipelines, and websites. Your engineering teams register entities in the catalog via YAML files that make up an explorable index of components, APIs, and resources. Backstage maintains the YAML files in git for you, so your catalog is backed up and recoverable with a complete history.
The Software Catalog solves two big problems:
One of the biggest challenges in a large engineering organization is making it easy for teams to maintain consistency and enforce standards across projects. Backstage's Software Templates help address that problem.
You can create templates inside Backstage that, with the click of a button, create new projects in places like GitLab and Github. So, rather than legislating conventions and standards. You can make it easy for teams to start new projects on the right foot.
Techdocs is a tool for storing your documentation with your code while still making it easy for engineers to view.
Your engineers write their documentation in Markdown and store it in source control, right next to their code. An MkDocs build step creates a documentation website when your CI pipeline builds the code. Backstage pulls in the site and displays it in your portal.
Your collection of software tools, libraries, and applications grows with your company. Every time your team writes some new code, signs up for a new cloud service, or adds a new API to the mix, they've created a new asset that you need to track.
You need a single source of truth for tracking these assets. You need a catalog.
The catalog acts as a knowledge management tool where your engineers can discover what tools are in use by the organization, where they are located, and who's responsible for them.
A catalog solves and prevents several problems:
Spotify describes Backstage as being "born out of necessity." Their infrastructure grew quickly, with development teams moving fast and distributed across several regions. As a result, their tools and processes were fragmented and hard to manage.
So, their teams were spending more time figuring out how to get started than they were writing, building, and testing code. They experienced the problems described in the section above and needed a single source of truth for their infrastructure.
They decided to build a layer that sat on top of their tools and infrastructure, making it easier to find, use, and manage their services and tooling. Spotify describes Backstage as a "developer portal powered by a centralized software catalog."
Since you download, install, and build Backstage yourself, you can run it anywhere you wish. This means it can run on-premises or in your cloud infrastructure, so it's easy to tie it directly to your systems without having to worry about opening it up to the outside world.
That makes Backstage's promise to "unify all your infrastructure tooling, services, and documentation" possible. Regardless of what you're running and where you're running it, you can make it available to Backstage's abstraction layer.
Backstage's plugin architecture, and the 130 plugins already available, means it's remarkably powerful and extensible "out of the box." Backstage can talk to AWS Lambda, Azure Pipelines, Datadog, Github Actions, and many more third-party tools.
So, Backstage has the power to fulfill its promises, but at what cost?
Cost? But didn't we say the Backstage is free as in beer? Yes, it is. But, as we also said, you download, install, and build Backstage yourself. Building a Backstage portal requires a great deal of work, and it also requires considerable maintenance.
Even though it's a CNCF offering, Backstage doesn't ship pre-built Docker containers. The installation requires Node.js and Yarn and, depending on your existing tech stack, may require additional resources. Backstage also requires a lot of customization and will likely need a dedicated team to maintain the systems and to keep the application up to date.
Where do you want to focus your development efforts? Maintaining Backstage requires time and effort on tasks that don't add value to your clients.
Backstage acts as an abstraction layer over your existing services and tools. It reads YAML files and feeds describing your infrastructure, but it has few querying and reporting capabilities. In a way, it acts as an RSS reader, displaying a syndicated feed that describes your assets.
configure8 offers a different approach to solving the developer experience problem. It's a hosted alternative to Backstage, so we maintain the infrastructure and operate the portal for you. You don't need to dedicate engineering staff to run your software catalog, and you can get up and running quickly without extensive preparation or design lead time.
configure8 addresses Backstage's architectural limitations, too. It maps your data in a graph database so you can run ad hoc and pre-configured queries that let you analyze how your components are related and how they've changed over time. So, you can get an understanding of your assets and learn how to improve.
In this article, we looked at Spotify's Backstage and what it has to offer your organization. Its plugin architecture and built-in features make it a compelling offering. But it's not a great fit for all organizations: Backstage requires up-front configuration and ongoing maintenance. So, we talked about how a SaaS option may work better for you.
Regardless of which solution you choose, a software and service catalog will help you manage your tools. Get started on one today!
This post was written by Eric Goebelbecker. Eric has worked in the financial markets in New York City for 25 years, developing infrastructure for market data and financial information exchange (FIX) protocol networks. He loves to talk about what makes teams effective (or not so effective!).