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:
![Screenshot of a form for creating an NSX Firewall Policy. The progress bar indicates four steps: "NSX Firewall Policy Settings: Basic Settings," "Security Policy Rules," "GitLab Authentication," and "Review." The current step, "Security Policy Rules," displays a section for entering security rules. The NSX Security Rules section includes fields for specifying the rule display name ("rule-1") and the source groups, which consist of IP ranges or CIDRs (e.g., "10.10.0.0/24" and "10.10.1.0/24").](https://www.soeldner-consult.de/wp-content/uploads/2024/06/NSX_Firewall_Policy.png)
![Screenshot of a form section for specifying NSX Firewall Policy Destination Groups. The section includes fields for defining the destination groups by IP, IP range, or CIDR (e.g., "10.20.0.0/24"). It also includes a field for specifying NSX Firewall Policy services ("service-test"), an action field set to "ALLOW," and an option to log the rule action with radio buttons for "Yes" or "No."](https://www.soeldner-consult.de/wp-content/uploads/2024/06/NSX_FirewallPolicy_Destination_Group-1024x504.png)
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
![Screenshot of the "Installed Actions" page in the Soeldner Consult application. The page lists various Git-related actions with their input parameters. The "git" action includes parameters for "command," "workingDirectory," "args," and "allowedToFail." The "git
" action has an input parameter for "repoUrl," which specifies the repository URL. The "sc:variables
" action is also listed, but without specified parameters. The interface includes navigation options on the left side for Home, APIs, Docs, and Manage.](https://www.soeldner-consult.de/wp-content/uploads/2024/06/Installed_Actions-1024x540.png)
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:
![Screenshot of the "Manage Components" page in the Soeldner Consult application. The page is used to create, update, and delete components using standard templates. The left navigation bar includes options for Home and APIs. The main section shows "Available Templates" with a search bar and a button labeled "Register Existing Component." A dropdown menu in the top right corner provides options for "Template Editor," "Installed Actions," and "Task List."](https://www.soeldner-consult.de/wp-content/uploads/2024/06/Manage_Componens-1024x146.png)
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:
![Screenshot of the "Template Editor" page in the Soeldner Consult application. The page allows users to edit, preview, and test templates and template forms. The left side of the screen displays the code for an "NSX Firewall Policy" template, showing parameters and properties such as "display_name," "description," and "owner." The right side shows a form with fields for "NSX Firewall Policy Display Name," "NSX Firewall Policy Description," and "Owner." A progress bar at the top indicates the steps: "NSX Firewall Policy Settings: Basic Settings," "Security Policy Rules," "GitLab Authentication," and "Review." A "Next" button is located at the bottom right.](https://www.soeldner-consult.de/wp-content/uploads/2024/06/Template_Editor.png)
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