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.

The instructions below assume that you have created a Backstage app. The commands must be executed from the root of your Backstage app. Refer to the Backstage official documentation for instructions on how to create a Backstage app.

info

For the plugins to work, make sure you have the following environment variable set when starting your Backstage app:

export NODE_OPTIONS=--no-node-snapshot

info

Plugins for SKE are compatible with Backstage apps created with Backstage version v1.24 or above. If you are running Backstage v1.23 or lower, you can check out their migration guide.

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.

For local development

To access the private npm registry in 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 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"}}'

For Docker

For Docker builds, you must update the packages/backend/Dockerfile in your Backstage app so that it can access the private npm registry.

Update the RUN command that is running the yarn install to mount a secret, as described below:

RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    --mount=type=secret,id=npmrc,target=/app/.npmrc,uid=1000,gid=1000 \
    yarn install --frozen-lockfile --production --network-timeout 300000

When running yarn build-image you now need to pass in the additional args --secret id=npmrc,src=$HOME/.npmrc to provide the npm credentials to Docker. Alternatively, you can update the build-image script in the package.json file to include the additional required flag.

warning

Make sure that the ~/.npmrc file is in the home directory of the user that is running the Docker build. Refer to the Local Development section for instructions.

Installing the frontend plugin

From the root of the backstage repository, run:

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

Update the EntityPage

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 following case to the EntitySwitch:

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

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

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.

Installing the backend plugin

From the root of the backstage repository, run:

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

Configure the Kubernetes integration

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>

You must now tell the backend plugin which cluster 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.

note

Currently, the backend plugin only supports clusterLocatorMethods of type config. As for the authentication, it supports authProvider: serviceAccount | oidc.

warning

For oidc authentication, you must ensure that, in the Backstage Token, there's a tok field with the accessToken to be used to access the Kubernetes cluster.

Add the backend plugin

Open the packages/backend/src/index.ts file and add the following import:

import { scaffolderModuleSkeExtensions } from '@syntasso/plugin-ske-backend';

Then register the backend plugin by adding the following:

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

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.

Start your Backstage app

You should now have two-way communication between Kratix and Backstage set up. You can now start your Backstage with the necessary environment variables set:

export NODE_OPTIONS=--no-node-snapshot
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
yarn dev

info

Make sure the port-forwarding to the MinIO instance is still running in a separate terminal.

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.

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.