Find me here:

INDEX

• Introduction
• Prerequisites
• Initial Setup
• Run Backstage Locally
• Customising Backstage
  • Plugins I've Added
  • Templates I've Created
  • My Arbitrary Rules
• Run Backstage In Minikube
• Conclusion

INTRODUCTION

This is a spin-off of my Automate All The Things DevOps project. While working on the Braindamage Edition - which will include a Developer Portal built with Backstage - I'm creating this smaller lab for anyone who wants to start experimenting with this tool.

Backstage is a framework for creating developer portals. This developer portal should act as a centralized hub for your organization, providing access to documentation, infrastructure, tooling, and code standards. It gives developers everything they need to create and manage their projects in a consistent and standardized manner. If you are new to Backstage, I invite you to read this brilliant series of articles by Alexandre Couedelo.

For a beefier implementation of Backstage check out the Backstage Minikube Lab Reloaded edition.

PREREQUISITES

• Active DockerHub account
• minikube installed
• kubectl installed
• helm installed
• nodejs installed
• nvm installed
• yarn installed

INITIAL SETUP

Before deploying Backstage in a Kubernetes environment (Minikube), we need to build it locally.

Make sure you are using Node.js version 18

nvm install 18
nvm use 18
nvm alias default 18

Make sure you are using Yarn version 1.22.19

yarn set version 1.22.19
yarn --version

Get GitHub PAT (Personal Access Token)

Navigate to the GitHub PAT creation page. Select "Generate new token (classic)".

Choose a name and a value for expiration. Under scopes select "repo" and "workflow". It should look something like this:

<

Click Generate token. Store the token somewhere safe.

Fork and clone the repo

Let's turn this whole deployment into your own thing.

1. Fork this repo. Keep the repository name "backstage-minikube-lab".
2. Clone the repo from your fork:

git clone https://github.com/<your-github-username>/backstage-minikube-lab.git

2. Move into the directory:

cd backstage-minikube-lab

2. Run the initial setup script. Come back when you are done:

chmod +x initial-setup.sh
./initial-setup.sh

4. Commit and push your customized repo to GitHub:

git add .
git commit -m "customized repo"
git push

RUN BACKSTAGE LOCALLY

Everything's ready to start playing with Backstage.

Create env var for your GitHub token

export GITHUB_TOKEN=<your-github-token>

cd into my-backstage directory

cd backstage/my-backstage/

Then run

yarn install
yarn tsc
yarn dev

Open your browser and go to localhost:3000. You should see the Backstage web UI.

Every time you make changes to the Backstage code, it's recommended you test it by running it locally with "yarn dev" like you just did. This will be much faster that testing every change in Minikube.

CUSTOMISING BACKSTAGE

Before deploying to Minikube, lets go over some things you'll find in this Backstage deployment.

Backstage is designed to be flexible and allow every organization to adapt it to their own needs. It is not a black-box application where you install plugins; rather, you maintain your own source code and can modify it as needed.

I've already added some custom stuff to the default Backstage installation that I think are essential.

Plugins I've added

Kubernetes plugin

The Kubernetes plugin in Backstage is a tool that's designed around the needs of service owners, not cluster admins. Now developers can easily check the health of their services no matter how or where those services are deployed — whether it's on a local host for testing or in production on dozens of clusters around the world.

It will elevate the visibility of errors where identified, and provide drill down about the deployments, pods, and other objects for a service.

GitHub Discovery plugin

The GitHub Discovery plugin automatically discovers catalog entities within a GitHub organization. The provider will crawl the GitHub organization and register entities matching the configured path. This can be useful as an alternative to static locations or manually adding things to the catalog. This is the preferred method for ingesting entities into the catalog.

I've installed it without events support. Updates to the catalog will rely on periodic scanning rather than real-time updates.

You can check the automatic discovery configuration under catalog.providers.github in the app-config.yaml and app-config.production.yaml files.

IMPORTANT: We use app-config.yaml for local testing (when running yarn dev) and app-config.production.yaml when deploying to Minikube.

Templates I've created

New Backstage System

Creates a new Backstage System with the provided information. A System in Backstage is a collection of entities (services, resources, APIs, etc.) that cooperate to perform a some function. For example, we will have a System called "my-app" that includes the my-app-frontend service, the my-app-backend service, the my-app-redis database and the my-app-backend API.

It generates a Pull Request which includes a new System manifest. When merged, the System catalog entity will be automatically added to the Backstage catalog by the GitHub Discovery plugin.

New Backstage Group

Creates a new Backstage group with the provided information.

It generates a Pull Request which includes a new Group manifest. When merged, the Group catalog entity will be automatically added to the Backstage catalog by the GitHub Discovery plugin.

New Backstage User

Creates a new Backstage user with the provided information.

It generates a Pull Request which includes a new User manifest. When merged, the User catalog entity will be automatically added to the Backstage catalog by the GitHub Discovery plugin.

New Node.js in existing repo

Creates all the boilerplate files and directories in an existing repo for deploying a new Node.js service in Kubernetes:

1. The application code directory and files, which will saved in the application-code directory.
2. The kubernetes manifests directory and files, which will be saved in the k8s-manifests directory.
3. The build and push GitHub workflow manifest, which will be saved the .github/workflows directory (working with GitHub Workflows is out of the scope of this lab).

It generates a Pull Request which includes all these files al directories.

New NGINX in existing repo

Creates all the boilerplate files and directories in an existing repo for deploying a new NGINX service in Kubernetes:

1. The application code directory and files, which will saved in the application-code directory.
2. The kubernetes manifests directory and files, which will be saved in the k8s-manifests directory.
3. The build and push GitHub workflow manifest, which will be saved the .github/workflows directory (working with GitHub Workflows is out of the scope of this lab).

It generates a Pull Request which includes all these files al directories.

My Arbitrary Rules

App-config management

The app-config is the file that defines the Backstage configuration. You will find three instances of app-config:

1. The app-config.yaml file: This is the config that will be used for development and testing purposes when running locally with yarn dev command.
2. The app-config.production.yaml file: This is the config that will be used for building the Docker image that will be deployed in Minikube. You will notice that it's missing the catalog configuration. That's because the catalog configuration will be passed in through a ConfigMap.
3. The helm chart values-custom.yaml file: Since the catalog configuration is something that might need to be modified more often, I decided it should be specified in a ConfigMap and not hard coded into the Docker image. You can find the catalog configuration in the values-custom.yaml file of the Backstage helm chart. Helm will create a ConfigMap with these values and pass it in to the Backstage pod at the time of creation.

Users and groups hierarchy

I decided that user and group hierarchy should be defined from the bottom up. To me, it makes more sense that childs should keep track of their parents than parents of their childs.

So we will not define the members of a group in the Group manifest, but we will define the group a user belongs to in the spec.memberOf of the User manifest.

Also, we will always have the spec.children value of Group manifests as an empty array and the spec.parent value filled with whoever the parent group of that group is. If it has no parent, the value of spec.parent should be "root".

RUN BACKSTAGE IN MINIKUBE

Ok, lets run Backstage in Minikube. Ctrl + C to kill the yarn dev process.

We first need to build and push the Backstage Docker image. Login to Docker

docker login

Then run the build-push-image.sh script

chmod +x build-push-image.sh
./build-push-image.sh

cd to the root of the repo:

cd ../..

If you have a Minikube cluster running, delete it first with minikube delete.

Now run the deploy-in-minikube.sh script to get everything setup:

chmod +x deploy-in-minikube.sh
./deploy-in-minikube.sh

Now go to localhost:8080 on your browser and Voilá!

CONCLUSION

That's it! This is your own Backstage implementation now.

Feel free to add your own plugins, templates and whatever else you might think of. Customize it to fit your own needs.

For a beefier Backstage implementation see the Backstage Minikube Lab Reloaded edition.

For more DevOps and Platform Engineering goodness, check out my Automate All The Things project.

Happy automating!