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:

export PRIVATE_REGISTRY_TOKEN="<YOUR_TOKEN_HERE>"

yarn config set npmScopes --json '{"syntasso": {"npmAlwaysAuth": true, "npmAuthToken": "$PRIVATE_REGISTRY_TOKEN", "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={isComponentType("service")}>
      {serviceEntityPage}
    </EntitySwitch.Case>

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

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

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

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

Installing the backend plugin

From the root of the backstage repository, run:

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

Configure

Add the following to the app-config.yaml file:

ske:
  scm:
    token: "my-access-token" # git access token
    repoUrl: "https://github.com/my-org/my-repo" # repository url
    type: "github" # optional; git provider, currently one of "github" or "gitlab" (used to determine username if `username` not set)
    username: "my-username" # optional; username for basic auth (default: inferred based on `type`)
    path: "catalog" # optional; path within the repository (default: "")
    branch: "main" # optional; branch to use (default: "main")
    defaultAuthor: # optional; git author details
      name: "my-name" # default: "SKE"
      email: "my@email.com" # default: ske@backstage.io

The backend plugin uses basic auth to authenticate against the Git provider. If you wish to specify a username/password, or use a Git provider other than GitHub or Gitlab, set the username field, and set the token field to the password or token. Otherwise, the username will be inferred from the type (e.g. "oauth2" for Gitlab). One of username or type must be provided.

The repoUrl is the repository to which Backstage will push the resource requests; you must configure your platform to reconcile on new documents.

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.

In the next section, you will configure your Platform cluster to reconcile on the documents pushed to the Git repository by the SKE actions.

Configuring the Platform

This section assumes you have a Kratix instance running following the quick start guide. Adjust the following steps to fit your installation in case you have a different setup.

Following the Quick Start, you should have both Kratix and Flux running on your platform. The easiest way to configure the platform to reconcile on the documents pushed to the Git repository by the SKE actions is to use the Flux CLI.

If you configured SKE to use GitHub, you can use the following command to bootstrap your platform, replacing the placeholders with your own values:

export GITHUB_TOKEN=<your-github-token>
flux bootstrap github \<
    --owner="<org>" \
    --repository="<repo>" \
    --branch="<branch>" \
    --interval="10s" \
    --path="catalog" # must match the `ske.scm.path` in the `app-config.yaml`

For other Git providers (including a generic git provider), check the Flux CLI docs.

tip

If you don't want to use the Flux CLI, you can check out the Flux documentation for other ways to configure your platform.

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.