docs: adding more golden path docs (#32493)
* docs: adding more golden path docs Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * cleanup Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * add instructions for checking todo list items Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * update ids so the number isn't baked into URL Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * add headings for all docs Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * add frontend plugin docs structure too Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> * fix bad link Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * address feedback Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> --------- Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com> Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Aramis Sennyey
@@ -0,0 +1,72 @@
|
||||
---
|
||||
id: getting-started
|
||||
sidebar_label: 001 - Getting started
|
||||
title: Getting started with Backstage
|
||||
---
|
||||
|
||||
The adoption journey is a bit different than the other Golden Paths. The goal of this guide is to prepare you for a successful implementation of Backstage in your organization. A technical understanding of Backstage is not needed for this Golden Path, just a desire to help the technical team that will be owning your Backstage instance.
|
||||
|
||||
:::info
|
||||
|
||||
I'd highly recommend poking around https://demo.backstage.io/ before continuing with this guide. It's a test instance of Backstage that provides a good foundation for what to expect from the tool as a user.
|
||||
|
||||
:::
|
||||
|
||||
## What is Backstage?
|
||||
|
||||
At a high level, Backstage is a framework for building developer portals. When implemented successfully, it can reduce toil for your developers by centralizing information like docs and ownership, reducing cognitive overhead due to tool fragmentation and simplify setting up new codebases or integrating with existing ones.
|
||||
|
||||
A few examples,
|
||||
|
||||
> My company tracks everything with spreadsheets. We have a list of all Github repos and who owns them, but it's becoming more and more of an issue to keep up to date. Teams aren't proactively updating it when new projects are created and it quickly falls out of date with reorgs and team charter changes.
|
||||
|
||||
Backstage can help! We provide a core plugin called Software Catalog that automates this process. Teams are asked to maintain a file in their repo with this ownership information and it gets automatically ingested into Backstage where you can view all projects in a single location.
|
||||
|
||||
> My developers have been complaining recently about having to use a growing number of different websites and tools in their day to day. It's getting hard to keep track of all of the tools and for those that we don't use frequently, we lose X minutes trying to remember how to access them.
|
||||
|
||||
Tool fragmentation is a real issue and Backstage can also help here! You can create plugins tailored for your company that talk to these external services. These plugins can be standalone or integrated with the Software Catalog for better context. Imagine all of your [CI/CD workflows visible directly](https://backstage.io/plugins/) on the page for your team's projects.
|
||||
|
||||
It's important to note that Backstage shouldn't be fully replacing these tools, we don't want to reinvent the wheel. The goal is to have all of the really important information in one place. The tool should still be where teams go to do more advanced or in depth work.
|
||||
|
||||
> We have been struggling recently with getting teams to use a standard template for new services. There's no standard set of libraries these services are using or standard infra management. It's increasingly difficult as a platform team to manage everything.
|
||||
|
||||
Backstage can help here too! The Scaffolder provides a templating framework that you can plug a Golden Path implementation to. Similar to Github template repos, this can provide a standard base for teams to create based off of.
|
||||
|
||||
> Our platform teams have been getting more and more support requests to help debug onboarding steps. We've documented these areas really well and there are plenty of examples in Git, but teams keep running into the same issues. It's always either a bad copy paste or they forget to update a template variable. We've started looking into a custom templating solution for this.
|
||||
|
||||
Backstage can help! With the Scaffolder, you can create a template that lets users fill in data through a form and uses that data to create a customized template output. This output is usually in the form of PRs to your various source control systems. Imagine you have a repo for traffic configuration, another for infrastructure management and a third for k8s manifests - with the Scaffolder, you can hide all of this complexity. You may still need to get reviews on the output PRs, but no more copy paste issues!
|
||||
|
||||
## What does adopting Backstage look like?
|
||||
|
||||
a.k.a "what am I signing myself up for?"
|
||||
|
||||
Successfully adopting Backstage usually looks something like this,
|
||||
|
||||
1. Setting up a PoC.
|
||||
2. Getting leadership buy-in.
|
||||
3. Identify a group of key stakeholders for the project and iterate with them aggressively.
|
||||
4. Launch to the larger organization.
|
||||
5. Drive Catalog adoption to 100%.
|
||||
6. Your Backstage implementation starts to receive plugins from developers outside of your team.
|
||||
|
||||
A truly successful Backstage implementation bridges delivering value to customers (developers), demonstrating returns to leadership, and fostering an inner source model. It's a long process but has huge dividends for those that achieve it!
|
||||
|
||||
## Getting started
|
||||
|
||||
Now that you know what to expect, let's walk through how to get started.
|
||||
|
||||
:::note
|
||||
|
||||
If you're non-technical, it is highly recommended to find a technical partner for help setting up a proof-of-concept for feedback.
|
||||
|
||||
:::
|
||||
|
||||
### Software Catalog
|
||||
|
||||
Let's go to https://demo.backstage.io/ together. When you first navigate to the page, you will be brought to the Software Catalog page. This is a view of all projects currently registered with the (Demo) Backstage instance. There are a series of filters that you can play around with. If you're _really_ interested, we recommend reading through [the software catalog system model](../../features/software-catalog/system-model.md).
|
||||
|
||||
Let's click into a Component, say "artist-lookup". This will bring you to a specialized view for that Component. Across the top, you can see tabs for "CI/CD", "API", "Dependencies", "Docs" and "TODOs". For your company, you can change this as you see fit. The important takeaway is that all of these tabs are automatically filtered for this Component which makes it easy to see how this could start to replace many navigation to other tools.
|
||||
|
||||
### Scaffolder
|
||||
|
||||
Let's go to https://demo.backstage.io/create now. This is the Scaffolder, a place to store reusable templates. Click the "Choose" button in the "Demo template". This will bring you to a form with some information to input. You don't need to fill this out. The main takeaway here is that this form is generated from YAML and doesn't require a frontend team to implement a custom form for each template you want to create.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
id: leadership-buy-in
|
||||
sidebar_label: 002 - Leadership buy-in
|
||||
title: Getting leadership buy-in
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
In this section, we'll be going over what leadership needs to hear to buy in to your pitch for a developer portal. We expect that you have a good idea of the problem that you want Backstage to solve at your company. If not, we recommend you start small. Look for something that is consistently frustrating developers you work with (this can include you). User interviews are a great way to better understand what needs to improve. It may be IT blocking the creation of new Github repos or databases. It might be 5 hours per week of manual toil that your whole organization has to do. It might be a slow time to production for new services or slow provisioning of test environments. Every company will be different. There is no one size fits all answer we can give you - and if we could, it wouldn't be well-tailored for _your_ leadership team.
|
||||
|
||||
## Milestones
|
||||
|
||||
Every Backstage adoption journey has well-known milestones.
|
||||
|
||||
1. You set up a PoC.
|
||||
2. You get some users.
|
||||
3. A group of users _really_ gets the value in the portal and jumps on it. They may even create their own plugins - great!
|
||||
4. You start to plateau with catalog adoption or daily active users.
|
||||
5. Leadership starts to get nosy about continued value.
|
||||
6. You hit a crossroads. Your team either starts to think about building something themselves or going for another off the shelf option or they sit down and do the work to get out of the plateau.
|
||||
7. If your organization made it this far, you likely now have blocking checks for catalog entries and Backstage is a weekly if not daily portal for your developers - congrats!
|
||||
|
||||
Step 4 and 5 are painful moments. Successful Backstage adoptions can lose steam quickly. That's the nature of these things, the excitement will eventually run out and people will go back to their day jobs. Another YAML file or cataloging tool is just overhead and extra toil, regardless of the problem you're solving. Getting leadership on the same page about the value of Backstage is the first step to a very successful adoption story.
|
||||
|
||||
### Recommendations
|
||||
|
||||
1. Bring something real to your leadership team. This can either be a true proof of concept or [the demo site](https://demo.backstage.io).
|
||||
2. Define metrics around what you're looking to drive up/down. That may be time to onboarding a new engineer, time to production for a new service, time to mitigate incidents, etc. As we say above, this is the meaty problem that is unique to your company that solving will really move the needle.
|
||||
3. Lower the barrier to adoption. Many people see yet another YAML file as overhead. If you have an existing cataloging solution, use that to simplify the onboarding process. If you don't, this might be a good opportunity to do that work.
|
||||
4. Knowledge silos. Every team has preferences on how to do things. Centralizing that data into a single interface while letting teams continue to do things how they want to is a powerful goal and something that Backstage can make happen.
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
id: setting-up-a-poc
|
||||
sidebar_label: 003 - Setting up a PoC
|
||||
title: Setting up a PoC
|
||||
---
|
||||
|
||||
If you're non-technical, this section should be completed by your technical partner.
|
||||
|
||||
Follow [our golden path for creating an app](../create-app/index.md). Once you have that set up, we recommend adding a few `catalog-info.yaml` files to a few repos/projects you own and setting up [the GitHub catalog provider](../../integrations/github/discovery.md).
|
||||
|
||||
At this stage, you likely want to just get the instance running on your local machine. We'll go over preparing your instance for production at the end of chapter 2.
|
||||
|
||||
You may be tempted to update the theme or add that one plugin your organization _needs_, but hold strong. We'll get there in chapter 3.
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: first-stakeholder-feedback
|
||||
sidebar_label: 004 - Stakeholder Feedback
|
||||
title: First round of stakeholder feedback
|
||||
---
|
||||
|
||||
Now that you have a PoC running, let's walk through how to get good feedback. You likely aren't the first person to hear about Backstage or maybe not even the first person to set up a PoC. There may be common pitfalls unique to your company that are worth knowing about - political, organizational or otherwise.
|
||||
|
||||
## Who to look for?
|
||||
|
||||
This depends pretty significantly on your organizational structure. If you have a dedicated platform organization or platform team, start with them. They will either be the technical owners of this application from the go, or will eventually take over ownership. Be kind to them. If you aren't from that organization, we recommend finding your technical partner from somewhere in that organization.
|
||||
|
||||
## What to listen for
|
||||
|
||||
1. IT slowness. Does your organization run on tickets? Are there specific tasks that feel like they should be automated but aren't?
|
||||
2. User toil. Your developers are super aware of what's slowing them down, they'll tell you the annoying manual parts of their job that they're hoping you can fix.
|
||||
3. Data sprawl. What services are your users struggling to remember? What vendors are critical but most users only touch once a month?
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: customize-your-instance
|
||||
sidebar_label: 005 - Customizing your instance
|
||||
title: Customizing your instance
|
||||
---
|
||||
|
||||
You now have the knowledge of what your users want and the go from leadership to continue investing in Backstage. Your job now is to customize your instance for your users to really get the value from. Let's dive in!
|
||||
|
||||
## Open Source or Build it yourself?
|
||||
|
||||
There's a huge community of plugins available for easy installation at https://backstage.io/plugins. We would recommend that you start here for any needs you may be trying to solve. Building a plugin yourself requires significant effort and can be hard to justify early on in your adoption story. If there is a clear gap in the existing offerings for your company, you should build something yourself - otherwise, save yourself the maintenance overhead.
|
||||
|
||||
## Customizing the theme
|
||||
|
||||
Many organizations are tempted to spend a long time making sure the portal resembles their other offerings. This is important but shouldn't be a months long ordeal. Get it looking close enough and iterate.
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
id: preparing-for-ga
|
||||
sidebar_label: 006 - Preparing for GA
|
||||
title: Preparing for GA
|
||||
---
|
||||
|
||||
We hope at this point that the developers you're working with have read the [golden path on deploying Backstage](../deployment/index.md). Your Backstage instance should be ready for the scale that comes with a full company launch.
|
||||
|
||||
## Launch Announcements
|
||||
|
||||
<!--TODO-->
|
||||
|
||||
## What to expect in the coming months
|
||||
|
||||
<!--TODO-->
|
||||
|
||||
## How to keep iterating
|
||||
|
||||
<!--TODO-->
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
id: plugin-ownership
|
||||
sidebar_label: 007 - Plugin Ownership
|
||||
title: Plugin Ownership
|
||||
---
|
||||
|
||||
You're now well on your way to a healthy Backstage instance! It's been launched to the whole company and you're loving the feedback developers are giving you. Some developers have even started broaching writing their own plugins.
|
||||
|
||||
## Inner source
|
||||
|
||||
Accepting internal contributions from other teams is a good sign that you are on the road to a developer portal tailored for your developers. This is a well paved path with many upsides, but a few downsides as well. As your Backstage instance grows in size and age, those same developers may be difficult to find. Your team may start to experience more and more struggle updating Backstage.
|
||||
|
||||
<!--TODO-->
|
||||
|
||||
## Registering Plugins in Your Catalog
|
||||
|
||||
<!--TODO-->
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
id: full-catalog
|
||||
sidebar_label: 008 - A Full Catalog
|
||||
title: Ensuring your catalog stays complete
|
||||
---
|
||||
|
||||
Along your Backstage journey (and any workflow migration journey), you will hit a point where incremental adoption is no longer easy. The new developers are no longer flowing into your tool like they once did. More and more projects are not being listed in your catalog. Something has to change.
|
||||
|
||||
## Enforcing Catalog Files in CI
|
||||
|
||||
<!--TODO-->
|
||||
|
||||
## Leadership Initiatives
|
||||
|
||||
<!--TODO-->
|
||||
@@ -19,6 +19,8 @@ Users should already have read through the summary section of the docs, "What is
|
||||
|
||||
We recommend you poke around the demo site to get a feel for what Backstage can provide. If you're technical, or working with someone technical, you can run through the steps in `golden-path/create-app` and `golden-path/deploying-backstage` to get something running for just your company.
|
||||
|
||||
## Getting leadership buy-in
|
||||
|
||||
## First round of stakeholder feedback
|
||||
|
||||
If you think Backstage is a good fit for your company, it's likely there are others that do or will think the same. You may have already identified them. For this initial round of feedback, share recommendations for what that group should look like, is there any required number of technical or non-technical members, do you need leadership involved at this point, etc.
|
||||
@@ -29,9 +31,7 @@ For non-technical users, it's recommended to find a technical partner to help st
|
||||
|
||||
At this point, we're assuming you already have an instance created through `golden-path/create-app` and `golden-path/deploying-backstage`. You should now start customizing it to your company's needs. We recommend you start small, write some catalog-info YAML files and start to build a personalized catalog.
|
||||
|
||||
## Second round of stakeholder feedback
|
||||
|
||||
## Getting leadership buy-in
|
||||
## Preparing for GA
|
||||
|
||||
## Plugin ownership and inner source mentality
|
||||
|
||||
Reference in New Issue
Block a user