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.
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
The Controller is released separately from SKE. Its releases can be found here.
The Controller can be installed using the helm chart.
You will need to start by adding the Syntasso Helm repository:
helm repo add syntasso https://syntasso.github.io/helm-charts
helm repo update
Configure values
Helm can accept values via the values file. Any configuration should be placed in a values.yaml file that is then passed in to the helm install command. For all available configurations, please refer to the default values file in Backstage Controller chart.
Below are instructions on how you could use the values file to configure SKE license and image registry.
The SKE license
Both the Backstage Controller image and the SKE Backstage Generator image used by the Controller are hosted in a private registry, to access these images, you will need to authenticate using the token you have been provided with.
The Backstage Controller chart will, be default, use a secret named syntasso-registry
in the kratix-platform-system
namespace. This secret is created and managed by the SKE operator helm chart.
If you wish to create a different image pull secret, you can run the following command:
kubectl create secret docker-registry YOUR-SECRET-NAME \
--namespace=kratix-platform-system \
--docker-server=registry.syntasso.io \
--docker-username=syntasso-pkg \
--docker-password=<YOUR TOKEN>
The above command creates a Kubernetes Secret in namespace kratix-platform-system
.
To use this secret in Backstage Controller chart, you can customize imageRegistry.imagePullSecret
in your values file.
# Configuration for the image registry
# Update these values if you are using a private image registry
imageRegistry:
imagePullSecret: YOUR-SECRET-NAME
# ...
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 following images are mirrored to your own image registry and tagged according to the version.
registry.syntasso.io/syntasso/backstage-controller
registry.syntasso.io/syntasso/ske-backstage-generator
You can then customize imageRegistry.host
in your values file:
# Configuration for the image registry
# Update these values if you are using a private image registry
imageRegistry:
host: "my-org.registry.io"
...
Deploy the Backstage Controller
Next, install Backstage Controller by running:
helm install backstage-controller syntasso/backstage-controller \
--namespace kratix-platform-system \
--wait \
--values values.yaml # This is optional. Only use if you are configuring custom values.
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
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.
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.