Edit

Adding your own Templates

Templates are stored in the Service Catalog under a kind Template. The minimum that is needed to define a template is a template.yaml file, but it would be good to also have some files in there that can be templated in.

A simple template.yaml definition might look something like this:

apiVersion: backstage.io/v1alpha1
kind: Template
metadata:
  # unique name per namespace for the template
  name: react-ssr-template
  # title of the template
  title: React SSR Template
  # a description of the template
  description:
    Next.js application skeleton for creating isomorphic web applications.
  # some tags to display in the frontend
  tags:
    - recommended
    - react
spec:
  # which templater key to use in the templaters builder
  templater: cookiecutter
  # what does this template create
  type: website
  # if the template is not in the current directory where this definition is kept then specify
  path: './template'
  # the schema for the form which is displayed in the frontend.
  # should follow JSON schema for forms: https://jsonforms.io/
  schema:
    required:
      - component_id
      - description
    properties:
      component_id:
        title: Name
        type: string
        description: Unique name of the component
      description:
        title: Description
        type: string
        description: Description of the component

Template Entity contains more information about the required fields.

Once we have a template.yaml ready, we can then add it to the service catalog for use by the scaffolder.

NOTE: When the publish step is completed, it is currently assumed by the scaffolder that the final repository should contain a catalog-info.yaml in order to register this with the Catalog in Backstage.

Currently the catalog supports loading definitions from GitHub + Local Files. To load from other places, not only will there need to be another preparer, but the support to load the location will also need to be added to the Catalog.

You can add the template files to the catalog through static location configuration, for example:

catalog:
  locations:
    - type: url
      target: https://github.com/spotify/cookiecutter-golang/blob/master/template.yaml
      rules:
        - allow: [Template]

Templates can also be added by posting the to the catalog directly. Note that if you're doing this, you need to configure the catalog to allow template entities to be ingested from any source, for example:

catalog:
  rules:
    - allow: [Component, API, Template]

For loading from a file, the following command should work when the backend is running:

curl \
  --location \
  --request POST 'localhost:7000/api/catalog/locations' \
  --header 'Content-Type: application/json' \
  --data-raw "{\"type\": \"file\", \"target\": \"${YOUR PATH HERE}/template.yaml\"}"

If loading from a Git location, you can run the following

curl \
  --location \
  --request POST 'localhost:7000/api/catalog/locations' \
  --header 'Content-Type: application/json' \
  --data-raw "{\"type\": \"github\", \"target\": \"https://${GITHUB URL}/${YOUR GITHUB ORG/REPO}/blob/master/${PATH TO FOLDER}/template.yaml\"}"

This should then have been added the catalog, and be listed under the create page at http://localhost:3000/create.

The type field which is chosen in the request to add the template.yaml to the Service Catalog here, will become the PreparerKey which will be used to select the Preparer when creating a job.

Adding form values in the Scaffolder Wizard

The spec.schema property in the Template Entity is a yaml version of the JSON Form Schema standard.

Here you can define the key/values and then the wizard will convert this to a form for the user to fill in when your template is selected.

You can find out much more about the standard and how to use it here: https://jsonforms.io