Skip to main content

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

The plugin can communicate with Kubernetes in two ways:

  • Via the Kubernetes API (recommended)
  • Via a Git repository (deprecated)

The following section will cover the first option. If you'd like to use the Git integration, you can skip to the Configure the Git integration section.

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

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.

Configure the Git integration​

info

The Git integration is deprecated. By configuring Backstage with the Kubernetes integration, you will get the following benefits:

  • Real-time status updates for the Promises and resources
  • Resources can be managed via different interfaces, for example, via kubectl directly.

If you have configured the Kubernetes integration, continue to add the Backend plugin.

To configure Backstage to talk to Kubernetes via a Git repository, add the following section to your app-config.yaml:

ske:
  mode: gitops
  scm:
    token: "my-access-token" # optional; 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 token field may not be provided when Backstage is configured with GitHub App credentials, as the GitHub App will be used to authenticate against the Git provider.

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

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.

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.

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.