A Quick Migration From Backstage to Port & What You Need to Know

Introduction

Building an internal developer portal often begins with some experimentation. Typically, we see users trying to build a basic software catalog and define some developer self-service actions. They then check how all of this would fit in a platform engineering initiative. In some cases, they begin by creating a “draft” internal developer portal in backstage. 

This post will cover how to move your data from Backstage to Port. We’ll show a quick and handy way of importing from backstage, and then will go deeper to discuss the more interesting stuff such as extending the data model, adding stateful objects and kubernetes data. 

The quick export

Let’s assume I’ve invested some time in creating a backstage internal developer portal and now I want to migrate all of it into Port. While I can work manually to migrate the data, the process can be tedious, which is why we developed an OSS tool that allows you to do the following at a click of a button:

• Data model definition - from backstage to Port blueprints.
• Ingesting data using the Backstage API
• Extending the data model using Port’s Blueprints.

To use the automatic migration all you need to do is:

1. Clone this repository git clone https://github.com/port-labs/backstage-import.git
2. Create a .env file with the following values

BACKSTAGE_URL=<your backstage url i.e https://demo.backstage.io>

PORT_CLIENT_ID=<your port client id>

PORT_CLIENT_SECRET=<your port secret>

3. Run the following command

./import.sh

‍

For more information, you can visit our official docs for this tool.

‍

Now that the migration is over, let’s take a deeper look at what actually happens, and use this as an opportunity to think about how Port can extend the internal developer portal built in Backstage. 

‍

{{cta_5}}

‍

A closer look at migration: from data model definition to adding Kubernetes resources to the internal developer portal

Let’s look at the three steps used for the migration and break them up to understand how Port extends backstage but also lets you leverage your existing backstage investment.

• Data model definition
• Ingesting data from Backstage API
• Optimizing blueprints according to relation usage

‍

Step 1: The internal developer portal data model or schema

As far as developer portals go, the first thing to do is consider what you want to pull inside the internal developer portal. Some people call this a taxonomy for the developer portal, and at Port, we call this capability “blueprints”. A Blueprint, or custom entity definition, is a data model that allows definition of the metadata associated with software catalog entities. Blueprints are the main building block of Port. Populated blueprints are catalog entities. Blueprints support the representation of any asset in Port, such as microservice, environment, package, cluster, databases etc. Port’s blueprint approach means that the product in itself is completely un-opinionated about how to build the data model, as a result of the understanding that engineering organizations want to be able to control the data model to fit their needs. 

‍

Backstage uses the C4 model as its recommended data model (you can read more in this blog post). Port also supports a C4 model blueprint template, based on GitOps. The strength of this approach is that it goes beyond microservices and catalogs underlying cloud resources, deployments and related dependencies. Here’s a set of blueprints that would cover the C4 model:

‍

If we were doing the migration manually, we would essentially convert “component” and “resource” objects from backstage and replace backstage’s “depends on” relation to Port relationships.

Step 2: Ingesting data - are we talking GitOps only?

Once the data model is ready - or, in other words, that the blueprints and relations exist - we need to ingest data into the developer portal. In this case we will query the backstage  Entities API and then all the entities will be formed in accordance with the blueprints.

‍

Note that in Backstage, all the entities are managed in GitOps using a catalog-info.yaml file living inside your repository. But there are other ways to get data into an internal developer portal.

Port is an API-first platform, so the way entities are inserted can be in various ways such as GitOps, Terraform, Pulumi, CI/CD, Exporters (Such as AWS exporter, K8s exporter), and any other place that can send a simple CURL request. While managing entities backstage-style using GitOps makes a lot of sense, let’s assume we want to continue using GitOps even after we migrated from backstage to Port (which natively supports Git).

When we click on the 3 dots button next to our user profile, we can export blueprint data at GitOps.

‍

In the following form we specify which blueprints we would like to manage via GitOps, and the format output as GitOps. You can also decide to manage it via terraform or a simple JSON if you like.

Step 3: extending the data model to Kubernetes and stateful objects

Now, once all the entities exist in Port, let’s begin extending the data model.

For example, in Backstage, because of its opinionated approach, there is a relation between Component -> User, and a Component -> Team, which reflects the ownership of the Component.

‍

While this might be true for some organizations, it doesn’t work for all of them, for instance when organizations would like to enforce assigning ownership only to teams. Once we’ve migrated into Port, cleaning this up through the blueprints should be fairly easy. 

‍

Another thing we can do is add stateful objects. A Running Service blueprint reflects the service as it appears in a specific environment, for example, staging, production, etc…

We can also add data about our runtime environment from Kubernetes, as is described here. 

Happy migration!

‍
{{cta_4}}