# Backstage

## Introduction to Backstage

[Backstage](https://backstage.io/) 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](https://backstage.io/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:

[Enable Backstage in Rafay Kubernetes Operations Platform | Internal Developer Portal Setup](https://www.youtube.com/watch?v=0Ok3zoAr8OY)

## Assumptions

- You have a targeted Kubernetes cluster imported/created inside the platform. If not, you can [start here](https://docs.rafay.co/clusters/overview/)
- 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**

- In the general settings, for **Endpoint** enter **[https://backstage.github.io/charts](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

## 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**

- 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**

- 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

## 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**.

- 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**.

## 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**

- 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.
- **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

- 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

- 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**

- 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.

- 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

- 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 as you will need that for the kubectl command to access the user interface locally.

## 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:

```
kubectl --kubeconfig <your kubeconfig file> port-forward -n backstage-ns svc/<name of deployment> 7007:7007
```

- 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!

## 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!