Backstage 👨🎤
A new home for engineers
👋 Hello hello!
Good to see you again. I’m currently sheltering in a cottage in Cornwall, in the middle of a storm. The UK goes back into lockdown again this week, so I’m bound to have a bunch more time to write. Silver linings.
If this is your first time here, hello! The goal of this newsletter is to discuss techniques for building better software and being more effective in high growth companies. I mix in longer form content — think a short blog post that you could read in 5 minutes — with some of my favourite links. Here’s some popular posts from the past few months:
Thanks!
Stephen
Backstage
Today, we’re going to talk about Backstage: an open-source developer portal developed internally at Spotify. A little disclaimer before I start: I’ve invested in a Backstage-related company! But I have skin-in-the-game: where I can, I put my money where my mouth is and invest in the tools that I think will be really useful.
Scaling problems for engineering orgs ⚙️
Before we get into what Backstage does, let’s go through a few recurring problems that high growth engineering organisations face. Picture a company that has approximately 100 engineers, over multiple teams, that is rapidly hiring.
Knowing what software you’re actually running
This sounds trite, but it’s surprisingly hard to get a single view of all the software that you own and operate.
Who owns which services and products
Before you grew quickly, collective ownership worked well. There was high shared context, and everyone knew a little bit about everything.
However, as you split into multiple teams, you need to distribute services and products to teams. Who owns what, and where do I go to talk to them about it?
Doing migrations
As Will Larson says, migrations are the sole scalable fix to technical debt. It’s not enough to create new software quickly: the superpower comes from being able to effectively and safely retire software.
Let’s imagine a migration from Python 2 to Python 3. How do you track what needs to be migrated? Which teams will be responsible for migrating what pieces of software? How far are you along this migration, and which teams do you need to chase to get things over the line?
Inevitably, this ends up being a Google Sheet Of Doom, along with a good helping of Slack nudging. It works in a pinch, but it feels like there could be a better way.
Creating and finding high quality documentation
Proper documentation is worth its weight in gold. Too often, it’s hard to find where it actually lives! In most cases I’ve seen, it ends up being a single README.md per service, with some extra documentation spread across intranet tools and Google Docs.
This feels weird: why is our documentation so primitive, and so far away from normal developer tools?
So, what is Backstage?
I think of Backstage as the homepage for engineers at a company. It’s the first place you go to answer any engineering question you have — what was deployed in the last 30 minutes? Who owns this service that is overloading our logging infrastructure? — or to take some action, such as deploying changes, or merging pull requests.
Quoting directly from the website:
Backstage is an open platform for building developer portals. Powered by a centralized service catalog, Backstage restores order to your microservices and infrastructure. So your product teams can ship high-quality code quickly — without compromising autonomy.
Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.
It was internally developed at Spotify, and open-sourced in March, 2020. It was recently accepted into the Cloud Native Computing Foundation’s Sandbox program, and is moving to an open governance structure — showing Spotify’s motivation to spread ownership and to widen adoption across the market.
What does it do, and how does it solve the above problems?
Below is only a small snippet of the total functionality of Backstage. It’s being actively developed, and new plugins are appearing on a weekly basis. Thus, this section is going to get out of date very quickly!
Plugin model turns Backstage into a platform
Backstage is a single page application composed of a set of of plugins. Plugins are pieces of software that extend Backstage to give it some capability, such as viewing the output of a CI job, viewing Sentry data, or storing a service catalog. The generic mechanism underneath the plugin model allows for extensibility.
For example, let’s say that we collect test coverage as part of our CI pipeline. Without running Backstage, I’m not sure where I would go to be able to look at that for any service. Perhaps I’d store it alongside the service in the repository, but there’s no chance for me to render that information in a nice way. What about if I wanted to find the top N services with the poorest test coverage? That seems hard to do, and would require me to write a custom script.
Enter Backstage! You can write a plugin to render this information, linking it back to the services. It also allows you easily extend Backstage to support whatever you’d like it to: a homepage for your machine learning models, a list of the datacentres that you operate along with the last time they were serviced.. whatever you need. You can also benefit from community contributed plugins, such as AWS Lambda, Sentry and New Relic.
Ownership as a first class citizen
Within the software catalog that Backstage offers, ownership is a required field. This makes it clear to others who is the first point of call for any piece of software. This seems a small feature, but is incredibly useful when you spend most of your time encountering new software.
Search over all software
As mentioned earlier, Backstage stores all of the software that you are running. When it has this information, it allows global search over all that software, making it easy to find extra information like deployments, error rates, configuration and who owns it. You can imagine this is very useful during an incident. See the below video for an example.
A single place to store documentation
TechDocs is directly integrated into Backstage. This gives you a single place to look at all documentation, that lives alongside the code that you’re writing. This allows you to make changes to documentation directly alongside the pull requests that change the code.
You can raise issues on documentation, which directly integrates into Stack Overflow Enterprise. This allows readers and teams to ‘close the loop’ on updating and correcting documentation in a way that used to be done through Slack, and chasing other humans. Watch the video below to get a quick intro!
Best of the internet 🔗
For this edition, I’m going fully Backstage. There’s tons of videos and content to get through embedded in the post, so I don’t think you need much more!
Introduction to Backstage at Spotify - Stefan Ålund
This is a great walkthrough of how Spotify use Backstage internally. I’d really recommend grabbing a cup of coffee and sitting down to watch this end to end. For what it’s worth, not all of these plugins have, or will, make it to the open source version. But it’s a view of the path ahead!
That’s all from this week’s High Growth Engineering. If you enjoyed it, I’d really appreciate it if you could do one of the following:
Share it with a friend that would find it useful.
Follow me on Twitter: @sjwhitworth
Subscribe: just hit the button below.
All the best,
Stephen