Skip to main content

SKE Backstage Generator

The SKE Backstage Generator provides automated generation of the necessary Template and Component manifests for your Promises and requested Resources.

These manifests are read by Backstage and are designed to work seamlessly with the SKE Backstage plugins.

Prerequisites​

SKE Backstage plugins​

The ske-backstage-generator uses an action from the ske-backend Backstage plugin. This action is used within the generated Template to create a Resource Request. The generated Components are also used by the ske-frontend Backstage plugin to display Promise and Resource metadata.

In order to utilise the Templates and Components, you should also install both the ske-backend and ske-frontend plugins into your Backstage instance.

See Configuring the Plugins for instructions.

Backstage Destination​

You must have a Destination created with the environment: backstage label. See the Kratix Backstage docs for setup instructions.

How does it work?​

The ske-backstage-generator image is intended to be run as part of your Configure Pipeline for your Promise and Resource Workflows. It will auto-generate Backstage Template and Component manifests, and schedule them to your Backstage Destination.

Promise Configure​

In a Promise Configure workflow, two Backstage manifests will be generated:

  • Promise Component: A Backstage Component representing the Promise.
  • Promise Template: A Backstage Template representing the Promise API (i.e. the CRD for Resources created from this Promise).

Check the YAML File Format for examples of these manifests.

Resource Configure​

In a Resource Configure workflow, a single Backstage manifest will be generated:

  • Resource Component: A Backstage Component representing the Resource.

Check the YAML File Format for examples of these manifests.

Accessing the SKE Generator image​

Pulling the image locally​

The image is hosted in a private registry. To access the image, you will need to authenticate using the token you have been provided with. For Docker, you can run the following command, providing your token as the password when prompted:

docker login ghcr.io --username syntasso-pkg

If you are using a different container engine, follow the docs for your specific tool.

Once you have authenticated, you should be able to pull the image:

docker pull ghcr.io/syntasso/ske-backstage-generator:v0.3.0

Pulling the image from your cluster​

Your Kubernetes cluster must have permission to pull this image from the private registry.

If you are following the quick-start guide, you can load the image directly to the Kubernetes cache. Different tools have different commands for this. For example:

# For minikube
minikube image load ghcr.io/syntasso/ske-backstage-generator:v0.3.0

# For KinD
kind load docker-image ghcr.io/syntasso/ske-backstage-generator:v0.3.0

For other tools, follow their specific documentation.

When using the image in your Workflows, you can define the secret you want to use for authentication within your Promise, see below for more details.

info

If your cluster is running in a secure environment, you may wish to pull this image and push it to an internal registry which your cluster has permission to pull from.

Using the image in your Workflows​

To use the ske-backstage-generator image, update your Promise definition to include the generator as a workflow step for both the Promise Configure and Resource Configure workflows:

Workflows section in a Promise file
  # ...
  workflows:
    promise:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: promise-configure
          namespace: default
        spec:
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-promise-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.3.0
            name: ske-backstage-generator
    resource:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: resource-configure
          namespace: default
        spec:
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-resource-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.3.0
            name: ske-backstage-generator

Once your Promise is updated, the generator will be run as part of your Workflows. If you install the Promise, you should see a Component automatically appearing in your Backstage instance, together with a new Template. If you use the Template to create a Resource, you should see the resource Component appearing as well as the Resource itself being created in your cluster.

In order to have the full status of your Promise or Resource request displayed in Backstage, you should place the aspect as the last image in the last pipeline of your workflow.

If the aspect needs to be used more than once in a Workflow, you should utilise the SKE Backstage Component Promise. Otherwise, you will observe only one of the components in Backstage, and Backstage will emit a warning:

{"level":"warn","message":"Detected conflicting entityRef component:default/my-request-jenkins already referenced by url:http://minio.kratix-platform-system.svc.cluster.local/kratix/backstage/resources/default/cicd/my-request/instance-configure/5cfaf/backstage/catalog-info.yaml and now also url:http://minio.kratix-platform-system.svc.cluster.local/kratix/backstage/resources/default/cicd/my-request/instance-configure-2/5cfaf/backstage/catalog-info.yaml","plugin":"catalog","service":"backstage"}

Authenticating against the image registry​

If you have not loaded the image to your Kubernetes cache or pushed it to an internal registry, you can define your authentication credentials via a docker-registry secret and refer to this secret in Pipeline definition in your Workflow.

You can create the secret with the following command, replacing YOUR_TOKEN with the token you have been provided with:

kubectl create secret docker-registry syntasso-registry \
  --docker-server=ghcr.io \
  --docker-username=syntasso-pkg \
  --docker-password=YOUR_TOKEN \
  --namespace kratix-platform-system
info

The secret must exist in the kratix-platform-system namespace as well as any other namespaces where users be able to make requests

The imagePullSecrets field in your Workflow can be used to refer to the new syntasso-registry secret.

  # ...
  workflows:
    promise:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: promise-configure
          namespace: default
        spec:
          imagePullSecrets:
            - name: syntasso-registry
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-promise-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.3.0
            name: ske-backstage-generator

This ensures that, when pulling the ske-backstage-generator image, Kubernetes will use the syntasso-registry secrets for authentication.

Customising the generated Components​

By default, the generator will create the Backstage Promise Component with default values for the metadata and spec fields. For a Promise, for example, it will look like this:

metadata:
  name: <Promise Kind>-promise
  title: <Promise Kind> Promise
  description: <Promise Kind> as a Service
  tags:
    - kratix
spec:
  lifecycle: production
  owner: kratix-platform
  type: kratix-promise
  # Other fields are left empty

You can customise these values by setting the following env variables in the workflow:

  • COMPONENT_NAME: the value of metadata.name
  • COMPONENT_TITLE: the value of metadata.title
  • COMPONENT_DESCRIPTION: the value of metadata.description
  • COMPONENT_TAGS: comma-separated list of values for metadata.tags
  • COMPONENT_TYPE: the value of spec.type
  • COMPONENT_LIFECYCLE: the value of spec.lifecycle
  • COMPONENT_OWNER: the value of spec.owner
  • COMPONENT_SYSTEM: the value of spec.system
  • COMPONENT_SUBCOMPONENT_OF: the value of spec.subcomponentOf
  • COMPONENT_PROVIDES_APIS: comma-separated list of values for spec.providesApis
  • COMPONENT_CONSUMES_APIS: comma-separated list of values for spec.consumesApis
  • COMPONENT_DEPENDS_ON: comma-separated list of values for spec.dependsOn

You can also customise the fields by setting the following annotations in the Promise or Resource object directly:

  • ske.backstage.component/name: the value of metadata.name
  • ske.backstage.component/title: the value of metadata.title
  • ske.backstage.component/description: the value of metadata.description
  • ske.backstage.component/tags: comma-separated list of values for metadata.tags
  • ske.backstage.component/type: the value of spec.type
  • ske.backstage.component/lifecycle: the value of spec.lifecycle
  • ske.backstage.component/owner: the value of spec.owner
  • ske.backstage.component/system: the value of spec.system
  • ske.backstage.component/subcomponentOf: the value of spec.subcomponentOf
  • ske.backstage.component/providesApis: comma-separated list of values for spec.providesApis
  • ske.backstage.component/consumesApis: comma-separated list of values for spec.consumesApis
  • ske.backstage.component/dependsOn: comma-separated list of values for spec.dependsOn

For example, to set spec.owner and spec.providesApis, you can update your pipeline stage with the snippet below:

Promise workflow with custom Component values
  #...
  workflows:
    promise:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: promise-configure
          namespace: default
        spec:
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-promise-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.3.0
            name: ske-backstage-generator
            env:
            - name: COMPONENT_OWNER
              value: "platform-team"
            - name: COMPONENT_PROVIDES_APIS
              value: "component/api/v1,component/api/v2"

Customising the generated Templates​

By default, the generator will create the Backstage Template with resource namespace as a required field. You can customise this behaviour by setting the following env variables in the workflow:

  • TEMPLATE_NAMESPACE: the default value of the resource namespace
  • TEMPLATE_NAMESPACE_FIELD_TITLE: the name of the resource namespace field in Backstage UI
  • TEMPLATE_NAMESPACE_FIELD_DESCRIPTION: the description of the resource namespace field in Backstage UI
  • TEMPLATE_HIDE_NAMESPACE: set to true if you would like to hide the namespace field from the generated resource Template. Resource namespace will default to TEMPLATE_NAMESPACE when it is set, otherwise will be set to default namespace.

For example, to generate the resource Template without the namespace field and set the resource namespace to my-team for all resource requests:

Promise workflow with custom Template values
  #...
  workflows:
    promise:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: promise-configure
          namespace: default
        spec:
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-promise-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.3.0
            name: ske-backstage-generator
            env:
            - name: TEMPLATE_NAMESPACE
              value: "my-team"
            - name: TEMPLATE_HIDE_NAMESPACE
              value: "true"

Providing a Resource Summary​

On the Resource Component page, it's possible to include a free-form text block to provide documentation about the resource.

To do this, set the ske.backstage.component/summary annotation on the Promise object:

apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  #...
  annotations:
    ske.backstage.component/summary: |
      Some information about this Promise.

      This accepts **markdown!**

The text will be rendered on each Resource Component page in Backstage.

SKE Backstage Component Promise​

The SKE Backstage Component Promise provides additional functionality to the SKE Backstage integration by offloading management of Backstage Components and Templates from your Promises.

You can install the Promise via kubectl:

kubectl apply -f https://syntasso-enterprise-releases.s3.eu-west-2.amazonaws.com/promises/ske-backstage-component-promise.yaml

Component updates with multiple Pipelines​

If your Promise or Resource workflow contains multiple Pipelines, you may wish to update the associated Component in Backstage at the end of each Pipeline. For example, the Resource status could be updated in every Pipeline to convey the latest information about the Resource to the requester in Backstage.

To do this, configure the SKE Backstage Generator to send a request to the SKE Backstage Component Promise in the Promise and Resource workflows by adding --make-request to the SKE Backstage Generator in every Pipeline in your Resource Configure workflow, along with the rbac permissions required by the image:

  # ...
  workflows:
    resource:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: resource-configure
          namespace: default
        spec:
          rbac:
            permissions:
              - apiGroups: ["syntasso.io"]
                verbs: ["*"]
                resources: ["backstagecomponents"]
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-resource-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.7.0
            name: ske-backstage-generator
            args:
            - --make-request
    promise:
      configure:
      - apiVersion: platform.kratix.io/v1alpha1
        kind: Pipeline
        metadata:
          name: promise-configure
          namespace: default
        spec:
          rbac:
            permissions:
              - apiGroups: ["syntasso.io"]
                verbs: ["*"]
                resources: ["backstagecomponents"]
          containers:
          - image: ghcr.io/syntasso/kratix-marketplace/jenkins-configure-pipeline:v0.1.0
            name: jenkins-promise-pipeline
          - image: ghcr.io/syntasso/ske-backstage-generator:v0.7.0
            name: ske-backstage-generator
            args:
            - --make-request

Running in this mode, the SKE Backstage Generator will not schedule the Backstage documents itself. Instead, it will delegate this responsibility to the SKE Backstage Component Promise.

This allows the Backstage Component document to be managed per-Resource, meaning Resource metadata such as the status can be updated across multiple Pipelines.

Generate a single Backstage catalog​

Using the SKE Backstage Component Promise, you can optionally choose to write a single catalog-info.yaml file for Backstage to read from, instead of the default behaviour of one catalog file per Promise or resource request.

To do this, there are two steps required:

  • Configuring the SKE Backstage Generator to write all of the Backstage manifests in a single catalog-info.yaml.
  • Configuring all of your Promises to use the SKE Backstage Component Promise.

First, apply the following config map to your Platform cluster:

apiVersion: v1
data:
  allInOne: "true"
kind: ConfigMap
metadata:
  name: ske-backstage-component-promise-config
  namespace: kratix-platform-system

Then configure all of your Promises which use the SKE Backstage Generator to use the --make-request option in the Pipeline, as illustrated in the section above.

info

To ensure that a single catalog-info.yaml file is created, you must ensure that all of your Promises which use the SKE Backstage Generator are set up to use the --make-request option in both the Promise and Resource workflows.

Configuring the allInOne field to true will cause the SKE Backstage Component Promise to aggregate the Backstage Component and Template files for all Promises and Resources into a single catalog-info.yaml file in the Backstage Destination.

With these changes, your SKE Backstage integration will result in a single catalog-info.yaml file being written to your Backstage Destination containing all of the generated Component and Template manifests.