Skip to content

Backstage

Introduction to Backstage

Backstage is an open platform developed by Spotify for building developer portals and enabling developer self-service. Powered by a centralized software catalog, Backstage enables application teams to ship high-quality code quickly — without compromising autonomy. It allows developers to work with a simpler portal that abstracts away complexity and deliver cloud-native applications faster. In addition, Backstage has an extensible framework that has allowed for an ecosystem of plugins solving a variety of use cases including:

  • CI/CD
  • Container Registry
  • Tech Documentation
  • Observability/Monitoring
  • Infrastructure Provisioning
  • Internal Developer Portal for building applications
  • Version Control/GitOps

Backstage also has native plugins for Kubernetes while supporting an ecosystem of plugins from different vendors such as ArgoCD, GitHub Actions, Snyk, and more.

What Will You Do

In this exercise you will:

  • Create a repository pointing to Backstage Helm repo
  • Create a custom catalog that syncs Backstage helm chart from the Backstage helm repo
  • Create the Backstage software add-on from the Backstage helm chart in the catalog
  • Add this Backstage add-on to a cluster blueprint so that we can publish this software to the cluster
  • Apply the cluster blueprint to your cluster so that backstage is installed
  • Access the Backstage UI from a local machine via kubectl port forwarding

You can follow along using the following YouTube video or going through the instructions below:

Assumptions

  • You have a targeted Kubernetes cluster imported/created inside the platform. If not, you can start here
  • You have downloaded the kubeconfig for your cluster and have kubectl installed successfully on your local terminal
  • If using the video, make sure you have provisioned a namespace called backstage-ns on your cluster.

Step 1: Create a Repository pointing to Backstage Helm repo.

  • Login to the console and go to your project where your cluster is located
  • Go to Integrations -> Repositories. Click New Repository
  • In the name enter backstage-helm-repo and for Type select Helm. Click CREATE

Create Backstage Helm Repo

  • In the general settings, for Endpoint enter https://backstage.github.io/charts. For Reachability, select Internet as this is a public repository
  • Click SAVE. Credentials are not needed as this is a public repository
  • You should now see the backstage-helm-repo in your repository list. In the list click the validate button (the icon with the checkmark). You should see validation successful

Backstage Repository Validate

Backstage Repository Validation Successful

Step 2: Create Custom Catalog Pointing To Backstage Helm Repo

  • Now, Go to Catalog. Click Manage Catalogs.
  • In the Custom Catalogs tab, click New Catalog.
  • For the name, enter backstage-catalog. For the repository, select the backstage-helm-repo you just created. Make sure Auto Sync Catalog is checked and click CREATE

Create Backstage Catalog

  • Click Sync Catalog. Then click Manage Catalogs at the top of the screen to go back to your catalog list. You should see your catalog with Sync Status of Success

Backstage Catalog List

  • Click the name of the catalog, backstage-catalog, that you just created. You should see a tile for Backstage representing the backstage catalog item

  • Click the backstage tile. Notice that now we have the entire Backstage helm chart available with all the versions, instructions and description

Backstage Catalog Item

Step 3: Create Namespace To Use For Backstage Add-On

In order to create an add-on, we need to create a namespace on the cluster.

  • Go to Infrastructure -> Namespaces. Click New Namespace.
  • For the name, enter backstage-ns. Select type Wizard and click SAVE.

Backstage Namespace Creation

  • In the wizard, click the Placement tab
  • Next in the wizard, skip configuration and click SAVE & GO TO PLACEMENT. In the placement section, check your cluster where we will deploy the namespace. Then click SAVE AND PUBLISH. Then click PUBLISH. Go back to the namespaces list. You should see your namespace, backstage-ns, with status Ready.

Backstage Namespace List

Step 4: Create Backstage Add On From Catalog

  • Go to Infrastructure -> Add-Ons. Click New Add-On -> Create New Add-On From Catalog
  • Select backstage from the add-on tiles by clicking on it (you can also search for it). Make sure the tile you select also has the name of the catalog you created earlier
  • In the details page for backstage, go to the VALUES YAML tab. Click the download button at the top right of the file and save it locally as values.yaml. We will be editing this values.yaml file to set up some custom parameters
  • Click Create Add-On
  • For the name, enter backstage-add-on and for the namespace select backstage-ns. Hit CREATE

Backstage Add-On Creation

  • In the new version wizard, enter v1 for the version name
  • For the Values File(s) first we need to edit the values.yaml file we downloaded earlier

  • Using a local text editor, edit the following in the values.yaml file and save your changes:

  • fullnameOverride: Enter backstage-instance. This is just a name for the backstage service. Backstage Full Name Override

  • postgresql.enabled: Go down to the postgresql section. For enabled, set it to true. We will be using postgres as the database for our backstage instance Backstage Postgres

  • Go back to the console. For the Values File(s) section, select Upload and upload the values.yaml file you just edited. Using the in-built text editor, make sure your changes you made locally are persisted

Backstage Add-On Version

  • Hit SAVE CHANGES. Your add-on is now created. If you go to the add-on list, you'll see backstage-add-on with type Catalog App and on Namespace backstage-ns

Step 5: Create Cluster Blueprint With Backstage Add-On.

  • Go to Infrastructure -> Blueprints. Since we're using a custom software add-on, we need to create a custom blueprint. Click New Blueprint in the custom blueprints tab
  • For the name, enter backstage-bp and select type Custom Blueprint. Click SAVE

Blueprint creation

  • In the general settings for blueprint, enter v1 for the version name. For the base blueprint, select default blueprint. In the blueprint dropdown, select minimal. Leave the version at the latest
  • Scroll down and go to the add-ons section, and click ADD MORE. In the dropdown list, select the add-on you created earlier, backstage-add-on, and select v1 for the version.

Backstage Add-On Blueprint

  • Click SAVE CHANGES. You should see the blueprint created, and if you go back to the blueprint list it will appear there.

Step 6: Update Cluster With Blueprint to deploy Backstage Add-On

  • Go to Infrastructure -> Clusters and navigate to your cluster
  • On the cluster card, you should see a settings wheel. Click that settings wheel and click Update Blueprint
  • Select backstage-bp for the blueprint and v1 for the version. Click SAVE AND PUBLISH
  • You should see the backstage-add-on as 1 of the add-ons getting deployed. The full operation should not take more than a few minutes. Add the end you will see all Add-Ons Are Ready and your backstage-add-on deployed successfully to backstage-ns

Backstage Blueprint Sync

  • Click the name of your cluster at the top. Go to the Resources tab. In the namespace dropdown, select backstage-ns
  • Under Deployment Resources on the left, select Deployments. You should see the backstage app deployment. Save the name of the deployment (in this case based on the screenshot below, backstage-add-on) as you will need that for the kubectl command to access the user interface locally

Backstage Deployment

Step 7: Access Backstage User Interface Locally

Now we are ready to access the Backstage. The Backstage UI is running on port 7007 so we will run a port-forward to access the instance running in Backstage on our localhost port 7007.

  • Open a Terminal window/command prompt and enter the following command filling in the placeholder for the kubeconfig file with your local kubeconfig file and for the service filling in the name of the deployment from the previous step (see below screenshot for an example where the name of the service is backstage-add-on):
kubectl --kubeconfig <your kubeconfig file> port-forward -n backstage-ns svc/<name of deployment> 7007:7007

Backstage Terminal Example

  • Next open a browser and go to localhost:7007. You should now see the Backstage User Interface and you are all set to go and leverage Backstage for developer self-service!

Backstage UI

Next Steps

Now that you have Backstage up and running you can use Backstage to enable developer self-service and publish plugins, run technical documentation, or leverage other Backstage functionality!