Backstage Crossplane Plugin

Crossplane is a control plane framework that extends Kubernetes with custom APIs. You define compositions and claims. Your teams then use the Kubernetes API to create and manage cloud resources through those APIs. It fits well with GitOps and other declarative workflows.

The Crossplane plugin for Backstage brings this picture into your portal. It shows the claims, composite resources, and managed resources that belong to a service. You can open each resource as YAML, copy it, or download it. You can see recent events for a resource. You can switch to a graph view to understand how the pieces connect.

This helps you debug faster. You can trace a claim to the cloud object without leaving Backstage. Developers get context on their own services. Platform teams keep a shared view for day two work. If you need guardrails, the companion permissions backend adds access controls for listing items, viewing YAML, and reading events.

The plugin works on its own. It pairs well with a Kubernetes Ingestor that can add the right annotations for you. Either way, you get clear visibility of Crossplane resources inside Backstage, in one place where your teams already work.

Installation Instructions

These instructions apply to self-hosted Backstage only.

Install the frontend package

Run this in the app package

Copy

yarn --cwd packages/app add @terasky/backstage-plugin-crossplane-resources-frontend

Add a Crossplane tab to the entity page

Open packages app src components catalog EntityPage.tsx

Import the Crossplane content from the plugin

Copy

// packages/app/src/components/catalog/EntityPage.tsx
import React from 'react';
import { EntityLayout } from '@backstage/plugin-catalog';
import { EntitySwitch, isKind, isComponentType } from '@backstage/plugin-catalog';
import { EntityAboutCard } from '@backstage/plugin-catalog';
import { Grid } from '@material-ui/core';

// Import the Crossplane entity content
import { EntityCrossplaneResourcesContent } from '@terasky/backstage-plugin-crossplane-resources-frontend';

Add a Crossplane route in the service entity page

Copy

// inside packages/app/src/components/catalog/EntityPage.tsx

const serviceEntityPage = (
  <EntityLayout>
    <EntityLayout.Route path="overview" title="Overview">
      <Grid container spacing={3}>
        <Grid item xs={12} md={6}>
          <EntityAboutCard />
        </Grid>
      </Grid>
    </EntityLayout.Route>

    {/* Crossplane tab */}
    <EntityLayout.Route path="crossplane" title="Crossplane">
      <EntityCrossplaneResourcesContent />
    </EntityLayout.Route>
  </EntityLayout>
);

Wire the service entity page if it is not already wired

Copy

// packages/app/src/components/catalog/EntityPage.tsx

export const EntityPage = () => (
  <EntitySwitch>
    <EntitySwitch.Case if={isKind('component')}>
      <EntitySwitch.Case if={isComponentType('service')}>
        {serviceEntityPage}
      </EntitySwitch.Case>
      {/* add other component type pages as you need */}
      {serviceEntityPage}
    </EntitySwitch.Case>
  </EntitySwitch>
);

If your project uses the new composability pattern with separated pages, place the Crossplane route under the relevant EntityLayout for your component types. The path will render as a Crossplane tab on the entity page.

Optional standalone page

If you want a top level page too, add a route in App.tsx

Copy

// packages/app/src/App.tsx
import React from 'react';
import { FlatRoutes } from '@backstage/core-app-api';
import { Route } from 'react-router';
import { Root } from './components/Root';

// Reuse the same Crossplane entity content for a simple page
import { EntityCrossplaneResourcesContent } from '@terasky/backstage-plugin-crossplane-resources-frontend';

export const App = () => (
  <Root>
    <FlatRoutes>
      {/* other routes */}
      <Route path="/crossplane" element={<EntityCrossplaneResourcesContent />} />
    </FlatRoutes>
  </Root>
);

You can also add a sidebar item that links to /crossplane if you want a global entry point.

Catalog annotations

This plugin reads Crossplane related annotations on your catalog entities. Many teams get these from a Kubernetes ingestion process. You can also add the needed annotations by hand in catalog files. Make sure your components include the Crossplane reference annotations your team uses. The plugin uses those to find claims, composite resources, and managed resources.

Backend installation

No backend package is required for this plugin.

Changelog

This changelog is produced from commits made to the Crossplane plugin since 5 months ago. It may not contain information about all commits. Releases and version bumps are intentionally omitted. This changelog is generated by AI.

Breaking changes

Crossplane plugin now uses a backend plugin for Kubernetes access. You need to install and configure the backend plugin and permissions. #89. Merged 10 days ago.
Legacy components now use the Legacy prefix. Update imports and usage if you rely on the old names. #64. Merged 2 months ago.

Features

Add MCP Action support in the Crossplane plugin. #89. Merged 10 days ago.
Add support for the new frontend system. #83. Merged 26 days ago.
Overhaul the Crossplane frontend UX. Add table filtering. Keep legacy components under the Legacy prefix. #64. Merged 2 months ago.
Auto link functions and providers under xpkg.crossplane.io and crossplane contrib to their source GitHub repos. #82. Merged 27 days ago.
Render YAML manifests in a clearer and stable order. #82. Merged 27 days ago.
Use the Kubernetes v2 API in CrossplaneV1ResourceGraph. Fall back to v2beta1 if v2 is not available. #67. Merged 2 months ago.

Bug fixes

Fix manifest generation for cluster scoped custom resource templates that are not backed by Crossplane XRDs. #82. Merged 27 days ago.

Upgrades

Upgrade to Backstage 1.43.3. #89. Merged 10 days ago.
Upgrade to Backstage 1.42.5. #82. Merged 27 days ago.
Upgrade to Backstage 1.40. Migrate scaffolder actions to zod schemas. #54. Merged 3 months ago.

Set up Backstage in minutes with Roadie

Focus on using Backstage, rather than building and maintaining it.

Get a demo