How to supercharge Backstage with the Cortex plugin

This article was originally published in December 2021. The content has been updated to reflect the evolution of the IDP landscape and provide a strategic path for organizations looking to get more value from their Backstage investment.

Many engineering teams begin their developer portal journey with Backstage, drawn in by the promise of a customizable, open-source solution. However, once the initial setup is complete, they often run into the well-known realities of high maintenance overhead, low developer adoption, and the challenge of keeping catalog data trustworthy.

The Cortex plugin for Backstage is the first step to solving these problems. It allows you to inject powerful engineering intelligence directly into your existing Backstage UI, providing the visibility and accountability needed to drive meaningful improvements. In this guide, we’ll walk through the technical steps to connect Cortex to your Backstage instance and begin the journey from a simple catalog to a true engine for engineering excellence.

Cortex has two different plugins for Backstage: one for the frontend, and one for the backend.

Frontend plugin

The frontend plugin is designed to mirror Cortex within Backstage, so the layout and information will be familiar. This plugin is responsible for making API calls to Cortex, fetching information, and displaying it within Backstage.

Step 1

To set up the frontend, first add the plugin within the packages/app directory of your Backstage instance:

cd packages/app
yarn add @cortexapps/backstage-plugin

This will add the plugin as a dependency within the package’s JSON, and will pull the plugin’s library into Backstage, which will allow it to be hooked up with Cortex.

Step 2

Navigate to packages/app/src, and create a new file called plugins.ts. Add the following to plugins.ts:

export { cortexPlugin } from ‘@cortexapps/backstage-plugin’;

Step 3

Next, navigate to packages/app/src/App.tsx — this file dictates what will be displayed on the frontend. First, import the file from the previous step:

And then add a new route, so that you can automatically go to the Cortex page by appending /cortex to your Backstage URL:

<Route path=“/cortex” element={<CortexPage /> } />

Step 4

Because you need an API key for Backstage to communicate with Cortex, you’ll also need to update the app-config.yaml file with a proxy config:

‘/cortex’:
  target: ${CORTEX_BACKEND_HOST_URL}
  headers:
   Authorization: ${CORTEX_TOKEN}

Cortex uses two different environment variables to avoid security vulnerabilities. If you run into issues during this stage, confirm that Backstage is pointing to the right URL for Cortex, and make sure that your token has a Bearer prefix.

This step is vital, since this is what allows Backstage to communicate with Cortex, and allows the plugin to fetch information for display.

Step 5

The steps above will set up the main Cortex page within Backstage. To add a Cortex tab for each entity, navigate to packages/app/src/components/catalog/EntityPage.tsx and import EntityCortexContent:

import { EntityCortexContent } from ‘@cortexapps/backstage-plugin’;

Then, update the serviceEntityPage with the following block to add the Cortex tab:

<EntityLayout.Route path=“/cortex” title=“Cortex”>
  <EntityCortexContent />
</EntityLayout.Route>;

Optional: Sidebar button

To add a sidebar button for Cortex, navigate to packages/app/src/components/Root/Root.tsx and add the following:

import { CortexIcon } from ‘@cortexapps/backstage-plugin’;

<SidebarItem icon={CortexIcon} to=“cortex” text=“Cortex” />;

Optional: Widgets

You can add a widget that will display Scorecard information for specific components. Within EntityPage.tsx, add the following:

import { CortexScorecardWidget } from ‘@cortexapps/backstage-plugin’;

<Grid item md={4} xs={12}>
  <CortexScorecardWidget />
</Grid>

Backend plugin

The backend plugin is responsible for making sure Backstage and Cortex stay up to date. Both platforms use YAML files to represent different services and entities. The backend plugin pushes the list of all the Backstage YAMLs into Cortex, where they’re converted to Cortex’s internal YAML, and then synced with Backstage. While you have the option to manually sync Backstage and Cortex, this plugin will take care of that automatically.

Step 1

To set up the backend plugin, you’ll first need to add the plugin library within the packages/backend directory of your Backstage instance:

cd packages/backend
yarn add @cortexapps/backstage-backend-plugin

Step 2

Within Backstage, navigate to packages/backend/src/plugins, and create a new file named Cortex.ts. Within Cortex.ts, copy and paste the following code:

import { PluginEnvironment } from ‘../types’;
import { createRouter } from ‘@cortexapps/backstage-backend-plugin’;

export default async function createPlugin(env: PluginEnvironment) {
  return await createRouter({
   discoveryAPI: env.discovery,
   logger: env.logger,
   cronSchedule: env.config.getOptionalString(‘cortex.backend.cron’) ?? ‘0 3,7,11,15,19,23 *’
  });
}

The cron expression will determine how frequently Backstage and Cortex sync. In this example, the two will sync every day, every four hours, starting at 3 a.m. This is fully configurable, so you can easily set the exact sync schedule you want, down to the second.

Step 3

Next, navigate to packages/backend/src, and within the index.ts file, import the file you just created:

import cortex from ‘./plugins/cortex’;

Then, add these lines to hook everything together:

const cortexEnv = useHotMemoize(module, () => createEnv(‘cortex’));
...
apiRouter.use(‘/cortex’, await cortex(cortexEnv));

Proxy config

Because we already added a proxy config when we set up the frontend plugin, it will already be in place for us. But, if you’re setting up the backend before the frontend, you’ll need to add the following in the app-config.yaml file:

‘/cortex’:
  target: ${CORTEX_BACKEND_HOST_URL}
  headers:
   Authorization: ${CORTEX_TOKEN}

From a smarter plugin to a complete solution

Once the plugin is set up and your catalogs are synced, you'll immediately see the value of Cortex's intelligence within your Backstage UI. Your teams can now see Scorecard grades, track progress against engineering initiatives, and get a clear picture of service health without leaving the environment they're used to.

This is a powerful first step. But as your organization matures, you'll find that simply displaying Cortex data in Backstage doesn't solve the core problem: the significant engineering effort required to maintain Backstage itself.

When you're ready to free your engineers from the burden of portal maintenance and unlock the full power of the Cortex platform, the next step is simple. With our Backstage Migration Helper, you can fully migrate your catalog to Cortex in minutes. You get to keep all your data and catalog structure while eliminating the TCO and adoption challenges for good.

Start by enhancing your Backstage instance with the Cortex plugin today, and when you're ready, a seamless path to a fully managed, turnkey IDP is waiting for you. Book a demo to learn more.