Skip to main content

Installing and Configuring the Plugins

The Backstage plugins for SKE are a set of plugins that provide additional functionality to Backstage. The plugins are:

  • @syntasso/plugin-ske-backend: The backend plugin for SKE.
  • @syntasso/plugin-ske-frontend: The frontend plugin for SKE.

Follow the instructions below to install and configure both plugins.

Prerequisites​

  • Backstage app running v1.40 or above: The SKE plugins are tested up to v1.50.4 the Backstage migration guide. If you do not have a Backstage app, refer to the Backstage official documentation for instructions on how to create a Backstage app.

  • Node.js 22+: Starting from Backstage v1.50, Node.js 22 or higher is required due to native module dependencies. Ensure your build environment and Docker images use Node 22+.

  • NODE_OPTIONS environment variable: Set the following when starting your Backstage app:

    export NODE_OPTIONS=--no-node-snapshot

Accessing the private npm registry​

The SKE plugins are distributed through a private npm registry. Please follow the steps below to enable access to it.

To access the private npm registry on your local machine, you will need npm config in a local ~/.npmrc file in your home directory. Create this file if it doesn't already exist, and add the following content:

# replace <YOUR_TOKEN_HERE> with the provided Syntasso registry token
@syntasso:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken="<YOUR_TOKEN_HERE>"
always-auth=true
info

For Yarn 3+, use the following command to set a local .yarnrc.yml file:

yarn config set npmScopes --json '{"syntasso": {"npmAlwaysAuth": true, "npmAuthToken": "<YOUR TOKEN HERE>", "npmRegistryServer": "https://npm.pkg.github.com"}}'

Installing the plugins​

For a self-hosted Backstage, from the root of the backstage repository, run the following to install the frontend plugin:

yarn add @syntasso/plugin-ske-frontend --cwd packages/app

Repeat this for the backend plugin:

yarn add @syntasso/plugin-ske-backend --cwd packages/backend

If you are using Spotify Portal for Backstage, follow the Spotify Portal installation guide to publish the plugin to your cloud instance before continuing with the configuration steps below.

Configuring the frontend plugin​

@syntasso/plugin-ske-frontend brings dedicated entity pages for Kratix Promises and Resources into the Backstage catalog. Teams can browse Promises, view and create Requests, and track the status of their requests — without leaving Backstage.

Update the EntityPage​

If your Backstage app uses the new frontend system (default since Backstage v1.49.0), the plugin is automatically discovered — no changes to EntityPage.tsx are needed. This is also the case if you are using Spotify Portal for Backstage.

The plugin registers the following extensions via its alpha entry point:

  • Promise Overview — displays the Overview tab for Promise entities
  • Resource Overview — displays the Overview tab for Resource entities
  • Resource Manage — displays the Manage tab for Resource entities

To verify the plugin is loaded, check your Backstage app configuration. The plugin should appear under @syntasso/plugin-ske-frontend/alpha in the resolved plugin list.

In the packages/app/src/components/catalog/EntityPage.tsx file, add the following to the list of imports:

import {
  KratixPromiseEntityPage,
  KratixResourceEntityPage,
  isKratixType,
} from "@syntasso/plugin-ske-frontend";

Find the line where the const componentPage is being declared. Add the KratixPromiseEntityPage and KratixResourceEntityPage cases to the EntitySwitch.

When updated, the componentPage variable should look similar to this, with any other additional case statements:

const componentPage = (
  <EntitySwitch>
    <EntitySwitch.Case if={isKratixType('promise')}>
      <KratixPromiseEntityPage>{entityWarningContent}</KratixPromiseEntityPage>
    </EntitySwitch.Case>

    <EntitySwitch.Case if={isKratixType('resource')}>
      <KratixResourceEntityPage>{entityWarningContent}</KratixResourceEntityPage>
    </EntitySwitch.Case>

    <EntitySwitch.Case if={isComponentType("service")}>
      {serviceEntityPage}
    </EntitySwitch.Case>

    <EntitySwitch.Case if={isComponentType("website")}>
      {websiteEntityPage}
    </EntitySwitch.Case>

    <EntitySwitch.Case>{defaultEntityPage}</EntitySwitch.Case>
  </EntitySwitch>
);

This states that for any Backstage Component definitions, the frontend plugin will display the custom KratixPromiseEntityPage for Components of type promise or kratix-promise and the KratixResourceEntityPage for for Components of type resource or `kratix-resource.

Plugin components​

Promise Overview​

KratixPromiseEntityPage renders a dedicated catalog page for Promise entities:

  • API group and resource name
  • Promise description and current status
  • Create button linking to the scaffolder template for new Resources
  • Dependency graph showing related Resource instances

Resource Overview​

KratixResourceEntityPage renders a dedicated catalog page for Resource entities:

  • Resource name, namespace, kind, and parent Promise
  • Optional Promise summary (markdown-rendered)
  • Current resource status
  • Dependency graph showing the relationship to the parent Promise

Resource Manage​

The Manage tab on KratixResourceEntityPage provides Resource lifecycle actions:

  • Pre-filled update form with the Resource's current spec
  • Read-only name and namespace fields
  • Delete button with confirmation dialog

Configuring the backend plugin​

The plugin can read from and write to your Kratix platform in two ways: directly via the Kubernetes API, or indirectly via a Git repository (GitOps mode). Follow the decision guidance below to decide on the approach most fitting for your platform.

Configure Backend Access​

Choose the mode that best fits your environment and operational requirements:

Kubernetes APIGitOps
Real-time status updates✓✗
Full resource management (kubectl-compatible)✓✗
Requires direct network access to the platform cluster✓✗
Routes all changes through a Git repository✗✓

Choose Kubernetes API mode if Backstage can reach the platform cluster over your network. This provides the most complete feature set, including real-time status updates and full resource management.

Choose GitOps mode if Backstage cannot access the platform cluster directly, or if your organisation requires all platform changes to flow through a Git repository.

The backend plugin will communicate with the Kubernetes cluster directly. For that, you will need to configure the Backstage Kubernetes integration. Check the Backstage docs for detailed information.

Once you configure the Kubernetes integration, you should have a kubernetes section in your app-config.yaml file similar to the following:

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: <my platform cluster url>
          name: kratixPlatform
          authProvider: serviceAccount
          skipTLSVerify: true
          serviceAccountToken: <service-account-token>
        - url: <another kubernetes cluster url>
          name: someOtherCluster
          authProvider: serviceAccount
          serviceAccountToken: <service-account-token>

Using OIDC Authentication​

If your Backstage instance authenticates users via an OIDC provider, you can configure the backend plugin to forward the user's OIDC token to the platform cluster. This allows Kubernetes RBAC to enforce access control based on the logged-in Backstage user's identity, rather than using a shared service account.

To enable this, set authProvider: oidc and oidcTokenProvider: <your-provider-name> on the cluster in your kubernetes config:

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: <my platform cluster url>
          name: kratixPlatform
          authProvider: oidc
          oidcTokenProvider: <your-provider-name>  # e.g. keycloak, okta, auth0
          skipTLSVerify: true

See the Configuring OIDC Authentication guide for full setup instructions.

You must now tell the backend plugin which of the configured clusters is the platform cluster. For that, add the following section to your app-config.yaml:

ske:
  kubernetes:
    # make sure this matches the name of the cluster you want to use
    platformName: kratixPlatform

If no ske.kubernetes section is present, the backend plugin will assume Backstage itself is running on the Platform cluster and will load the cluster configuration from the local machine/pod.

Add the backend plugin​

Open the packages/backend/src/index.ts file and register the backend plugin by adding the following:

backend.add(import("@syntasso/plugin-ske-backend"));

Once both packages are added and configured, from the root of your Backstage app, run:

yarn install

Your backstage instance is now ready to use the SKE plugins.

Using the actions​

Once both your frontend and backend plugins are installed and configured, your backstage should now have the SKE actions available and it should be able to render Kratix resources in the catalog.

To access the documentation for the SKE actions, check the actions documentation on your Backstage instance, which is available on the /create/actions endpoint.

Next​

The next guide will show how you can use the SKE Backstage Generator to automatically generate Backstage entities from your Promises. If you want to manually configure your Promises, check the YAML File Format reference.