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.
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
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
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
\
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.
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.
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
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.
