Skip to main content

Generating Backstage Components

The Backstage Controller generates Backstage components and templates for Promises and Resource Requests.

Prerequisites​

SKE installation​

Backstage Controller has dependency on SKE. If you haven't installed SKE, please refer to the SKE installation guide.

warning

You will need SKE 0.28.0 or later for Backstage Controller to work.

SKE Backstage plugins​

The generated Backstage Templates reference an action from the ske-backend Backstage plugin, this action is used 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 installation instructions.

Backstage Destination​

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

Installing the Backstage Controller​

Via the SKE Operator Helm Chart​

warning

You will need 0.52.0 of the SKE Operator Helm Chart

The Backstage Controller is installed by the SKE Operator and can be deployed via the SKE Operator Helm Chart.

To deploy the Backstage Controller via the SKE Operator Helm Chart, configure the backstageIntegration values. Most crucially, you will need to set backstageIntegration.enabled to true.

You can use the deploymentConfig.resources to configure the resource allocations for the Backstage Controller deployment.

backstageIntegration:
  enabled: true
  version: "latest"
  deploymentConfig:
    resources:
      limits:
        memory: "256Mi"
        cpu: "100m"
      requests:
        memory: "256Mi"
        cpu: "100m"

Image registry for Air-gapped Environments​

You may want to manage the Backstage Controller images within your own environment either due to air-gapped requirements or other security measures.

To do this, you will need to set up image mirroring and configure the Backstage Controller distribution to pull images from your own registry.

You must ensure that the Backstage Controller image is mirrored in your own image registry and tagged according to the version.

registry.syntasso.io/syntasso/backstage-controller

As is the case for the SKE Operator and SKE Platform images, the Backstage Controller will use registry configured via the imageRegistry.host when pulling images. If have changed the name of the Backstage Controller image in your internal registry, ensure that the imageRegistry.backstageControllerImage.name is updated to reflect this.

Deploy the Backstage Controller​

Having updated the Helm values, install the Backstage Controller by running:

helm install ske-operator syntasso/ske-operator \
  --namespace kratix-platform-system \
  --wait \
  --values values.yaml

Via the SKE Integrations CRD​

warning

You will need v0.19.0 of the SKE Operator or later

The SKE Operator includes a Custom Resource Definition (CRD) for managing SKE Integrations such as Backstage. Only one instance of a Backstage SKE Integration can be created by the SKE Operator in a given cluster.

If both the SKE Operator and SKE are deployed on your cluster, you can deploy the Backstage Controller by creating a SKE Integration. Create a file named backstage-integration.yaml with the following contents:

apiVersion: platform.syntasso.io/v1alpha1
kind: SKEIntegration
metadata:
  name: backstage-integration
spec:
  type: backstage
  version: v0.99.0 # The desired version of the Controller
  deploymentConfig:
    resources:
      limits:
        memory: "256Mi"
        cpu: "100m"
      requests:
        memory: "256Mi"
        cpu: "100m"

Apply the file with kubectl:

kubectl apply --filename backstage-integration.yaml

The operator will then install the Backstage Controller and the desired configurations.

How does it work?​

The SKE Backstage Controller creates a Workflow that automatically generates the Backstage components and templates for your Promise. This Workflow runs in addition to the Configure Workflow for your Promises and Requests.

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

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

Labelling Promises for automatic file generation​

To generate Backstage Components and Template for your Promise, as well as Components for requests for that Promise, label your Promise with kratix.io/backstage: true.

kubectl label promises PROMISE_NAME kratix.io/backstage=true

Or add the label to the Promise spec:

apiVersion: platform.kratix.io/v1alpha1
kind: Promise
metadata:
  name: my-promise
  labels:
    kratix.io/backstage: "true"

Customize Backstage Components​

You can customize the automatically generated Backstage Components and Templates by creating BackstageEntityCustomization:

apiVersion: platform.kratix.io/v1alpha1
kind: BackstageEntityCustomization
metadata:
  name: my-customization
spec:
  entityGenerationOptions:
    promise:
      component: # options for the generated Promise Component
        name: my-name # Value for metadata.name
        title: my-title # Value for metadata.title
        description: my-description # Value for metadata.description
        tags: tag1,tag2 # Values for metadata.tags
        type: my-type # Value for spec.type
        lifecycle: my-lifeCycle # Value for spec.lifecycle
        owner: my-owner # Value for spec.owner
        system: my-system # Value for spec.system
        subComponentOf: parent-resource # Value for spec.subcomponentOf
        providesAPIs: api1,api2 # Values for spec.providesAPIs
        consumesAPIs: api3,api4 # Values for spec.consumesAPIs
        dependsOn: dependency1,dependency2 # Values for spec.dependsOn
      template: # options for the generated Promise Template
        hideNamespace: false # Whether to hide the namespace field
        defaultNamespace: default # Default namespace to use
        namespaceFieldTitle: Namespace # Title for the namespace field
        namespaceFieldDescription: "Your team's namespace" # Description for the namespace field
        singleSpecPage: false # Whether to generate a single spec page for the template
        title: my-title # Value for metadata.title
        description: my-description # Value for metadata.description
        tags: tag1,tag2 # Values for metadata.tags
        type: my-type # Value for spec.type
        lifecycle: my-lifeCycle # Value for spec.lifecycle
        owner: my-owner # Value for spec.owner
    resource:
      component:
        name: my-name # Value for metadata.name
        title: my-title # Value for metadata.title
        description: my-description # Value for metadata.description
        tags: tag1,tag2 # Values for metadata.tags
        type: my-type # Value for spec.type
        lifecycle: my-lifeCycle # Value for spec.lifecycle
        owner: my-owner # Value for spec.owner
        system: my-system # Value for spec.system
        subComponentOf: parent-resource # Value for spec.subcomponentOf
        providesAPIs: api1,api2 # Values for spec.providesAPIs
        consumesAPIs: api3,api4 # Values for spec.consumesAPIs
        dependsOn: dependency1,dependency2 # Values for spec.dependsOn
  destinationSelectors: # optional
  - matchLabels:
      environment: backstage
  containers: # optional
    - name: add-backstage-group
      image: ghcr.io/syntasso/run-customization:v0.0.1

Once you have created the BackstageEntityCustomization, you can label your Promise with kratix.io/backstage-customization: my-customization to apply the customization to the Promise and its Resource Requests:

kubectl label promises PROMISE_NAME kratix.io/backstage-customization=my-customization
tip

Backstage Customizations are cluster-wide resources, so ensure create them with unique names

Custom containers​

The containers defined in the customization will run after the backstage-gen container which generates the Components and Templates. They can be used to modify the existing catalog-info.yaml file created by the ske-backstage-generator or it can generate new files. This customization will apply to all Promises with label kratix.io/backstage: "true" as well as Resource Requests for these promises.

info

If you want to a particular Resource Request to not have a Backstage Component generated, you can label the Resource Request with kratix.io/backstage: "false".

If you want to edit the Entities or generate different files based on whether the Workflow is running for a Promise or Resource Request, the container can query the KRATIX_WORKFLOW_TYPE environment variable. For Promises, this is equal to promise-backstage-gen and for resources, resource-backstage-gen.

Destination Selectors​

By default, Destination selectors defined in the customization will apply to all generated Backstage components. You can use these to make sure that generated components are only scheduled to your Backstage destinations.