Internal Developer Platforms Series – Part 15: Backstage Software Templates II

After having introduced Software Templates in the last step, it is now time to cover some details about working with the Scaffolder and espacially with parameters and steps.

Backstage parameters

In Backstage Scaffolder, parameters (often referred to as inputs) are values that can be provided by the user when they create a new project using a scaffolder template. These parameters make templates flexible and reusable by allowing customization without modifying the template itself.

Below is an example template that includes parameters and their usage in steps:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: my-template
  title: My Template
  description: A template with parameters
spec:
  parameters:
    - title: Project Information
      properties:
        name:
          title: Project Name
          type: string
          description: The name of the project
          ui:field: StringInput
        description:
          title: Project Description
          type: string
          description: A brief description of the project
        owner:
          title: Owner
          type: string
          description: The owner of the project
          ui:field: OwnerPicker

  steps:
    - id: fetch
      name: Fetch Template
      action: fetch:plain
      input:
        url: 'https://example.com/path/to/template'
        targetPath: './{{ parameters.name }}'

    - id: rename
      name: Rename Files
      action: filesystem:rename
      input:
        files:
          - from: 'old-file-name.txt'
            to: '{{ parameters.name }}.txt'

    - id: update-readme
      name: Update README
      action: filesystem:replaceInFile
      input:
        path: 'README.md'
        search: 'PROJECT_NAME'
        replace: '{{ parameters.name }}'

As described in the last blog post, parameters are defined in the parameters section of the template YAML file. Each parameter has attributes that specify its name, type, description, and other options such as default values and validation rules.

Paramters can be quite flexible: Amont others, you can use textboxes, checkboxes, lists, nested lists. The following screenshots show the formular for a NSX request formular:

Behind the scenes, Backstage Scaffolder uses JSON Schema to define the structure, constraints, and defaults for input parameters. This schema is then used to generate forms automatically using react-jsonschema-form. The form generated by RJSF ensures that the user inputs adhere to the defined schema, providing a seamless and error-free user experience.

Scaffolder steps

Backstage Scaffolder comes with a set of built-in steps. These are actions that can be used within a scaffolder template to automate common tasks. 

A step consists of an id, a name, an action, as well as input and output

You can browse the actions either in the Backstage documentation or in your Backstage instance if you open the URL https://<<backstage-url>>/create/actions

When working with steps, it is quite important to familiarize itself with filters that can be used in steps:

The provided built-in filters are used to manipulate and transform data within scaffolding templates. These filters are based on the Nunjucks templating language, which allows for powerful string and data manipulation. Examples for built-in filters are upper, lower, trim or replace, but there are also more sophisticated filters. For example, the parseRepoUrl filter parse a repository URL into its components, such as owner, repository name, and more.

The following is an example of an built-in filter:

- id: log
  name: Parse Repo URL
  action: debug:log
  input:
    extra: ${{ parameters.repoUrl | parseRepoUrl }}

Writing and viewing templates is sometimes cumbersome. Luckily, the GUI supports some testing and provides a Template Editor:

You can open the Editor either from the GUI or by navigating to /create/edit page.

The following screenshot shows the Template Editor for the NSX Firewall Scaffolder workflow shown above:

Built-in Actions

In Backstage Scaffolder, built-in actions are predefined operations that can be used in scaffolding templates to automate tasks during the scaffolding process. These actions are categorized into several types based on their functionality. Below, we show the main categories of built-in actions:

• Git Actions
• Fetch Actions
• Filesystem Actions
• HTTP Actions
• Shell Actions
• Templating Actions
• Publishing Actions
• Miscellaneous Actions

The following example shows a Git action to clone a repo.

- id: clone-repo
  name: Clone Repository
  action: git:clone
  input:
    url: 'https://github.com/my-org/my-template-repo'
    branch: 'main'  # Optional
    targetPath: './my-directory'  # Optional

In this blog post, we showed how to work with parameters, steps and actions. In the next blog post, we will show how to create a custom action.

> Click here for Part 16: Backstage Software Templates III