Skip to main content

Configuring Backstage

To integrate Kratix with Backstage, you need to configure both Backstage and Kratix so that they can communicate with each other.

This document covers the steps to configure Backstage to be able to read its catalog from an S3-compatible Bucket or Git repository.

This document will cover:

  • Creating a new Backstage app
  • Configuring catalog discovery from a state store

Creating a new Backstage app​

info

If you already have a Backstage app, you can skip this step.

Following Backstage's official documentation, you can bootstrap a new Backstage app by running the following command:

npx @backstage/create-app@latest

Once the command completes, you should have a new directory with a Backstage app. You can navigate to the directory and start the app by running:

cd backstage
yarn dev

At this point, you should see the Backstage app running at http://localhost:3000 with some example data.

For further information or for troubleshooting, please refer to the official documentation.

Catalog Discovery​

For Backstage to get its catalog automatically populated from Kratix Promises, you need to configure your instance to read its catalog from the same state store that Kratix will be later configured to write to.

You can follow the official Backstage documentation for details on how to configure the integration according to your state store:

  • For S3-Compatible buckets, check this page.
  • For Git repositories, the configuration depends on the specific provider. For GitHub integration, for example, check this page.

The following steps will guide you through the process of configuring Backstage to read its catalog from a S3-compatible bucket, and will assume you have deployed Kratix following the quick start guide.

Configure the Integration​

Following the Quick Start guide, you should have a Kratix instance running alongside with a MinIO instance. You can validate the setup by running the following command:

kubectl get pods -n kratix-platform-system

You should see the following pods running:

NAME                                                  READY   STATUS    RESTARTS   AGE
kratix-platform-controller-manager-6599cb4456-gc9zz   2/2     Running   0          109s
minio-587dd4c7c4-f294z                                1/1     Running   0          108s

You will configure your Backstage to fetch the catalog from the MinIO instance.

Following the AWS S3 Locations documentation, open the app-config.yaml file and, under the integrations key, add the awsS3 configuration as follows:

integrations:
  awsS3:
    - endpoint: "http://MINIO_ADDRESS"
      s3ForcePathStyle: true
      accessKeyId: ${AWS_ACCESS_KEY_ID}
      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}

Before starting your Backstage, make sure to set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to minioadmin and minioadmin.

Replace MINIO_ADDRESS with the address of your MinIO instance. If you are running Kratix with minikube, you can get the address by running:

minikube service minio -n kratix-platform-system --url

For other environments, you can open a port-forward to the MinIO service:

kubectl port-forward -n kratix-platform-system svc/minio 31337:80

and use http://localhost:31337 as the endpoint.

warning

Unless you can access the MinIO instance without port-forwarding, you must leave the terminal running the minikube service/port-forward command open for the duration of the Backstage app.

Configure the Discovery​

Next, configure the AWS S3 Catalog Discovery. First, open the app-config.yaml and add the following under the catalog key:

catalog:
  rules:
    - allow: [Component, Template] # Make sure to allow at least "component" and "template" entities
  providers:
    awsS3:
      kratix-minio:
        bucketName: kratix
        prefix: backstage/
        region: us-east-2
        schedule:
          frequency: { seconds: 10 }
          timeout: { seconds: 30 }
    rules:
    - allow: [Component, Template] # Make sure to allow at least "component" and "template" entities

Since the AWS provider is not one of the default Backstage providers, you will need to install the AWS Catalog plugin.

# From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-aws

Once you've done that, you'll also need to register the package in packages/backend/src/index.ts:

backend.add(import('@backstage/plugin-catalog-backend-module-aws/alpha'));

Configuring Kratix​

At this moment you have Backstage configured to read its catalog from an external state store. Next, you must configure Kratix so it can write Backstage entity data to the same state store.

The steps below will build from the previous section and assume you have a Kratix instance running as described in the quick start guide. If your Kratix is deployed differently, please adjust the steps accordingly.

Configure the State Store​

The quick start guide already configures a Kratix State Store pointing to a bucket in the MinIO instance. You can validate the setup by running the following command:

kubectl get bucketstatestores.platform.kratix.io

The output should look like this:

NAME      AGE
default   1m

If you inspect the state store definition:

kubectl get bucketstatestores.platform.kratix.io default -o yaml

You should see something similar to the following:

apiVersion: platform.kratix.io/v1alpha1
kind: BucketStateStore
metadata:
  name: default
spec:
  authMethod: accessKey
  bucketName: kratix
  endpoint: minio.kratix-platform-system.svc.cluster.local
  insecure: true
  secretRef:
    name: minio-credentials
    namespace: default

Note how the bucketName field matches the bucketName you configured in the Backstage app-config.yaml file. If you are using a different deployment setup, make sure to update the configurations accordingly

Configure a Destination for Backstage​

Next, you must configure a destination for the Backstage entities. This is done by creating a Destination resource in Kratix. The Destination resource will point to the state store you configured in the previous step, writing to the directory where Backstage expects to find its entities.

Create the Destination resource by running the following command:

cat <<EOF | kubectl apply -f -
apiVersion: platform.kratix.io/v1alpha1
kind: Destination
metadata:
  name: backstage
  labels:
    environment: backstage
spec:
  stateStoreRef:
    kind: BucketStateStore
    name: default
  path: backstage
  strictMatchLabels: true
EOF
info

The path field should match the path you configured in the Backstage app-config.yaml file, under the catalog. If you are using a different deployment setup, make sure to update the configurations accordingly.

Next​

Great! Kratix is now configured to write to the same state store that Backstage is configured to read its catalog from. At the moment, that's a one-way communication.

In the next guide you will configure Backstage to write to a state store, and configure Kratix to read from it.