OnCallReadyStart learning

Infrastructure as code Lesson 42.18 · Platform Engineering: Backstage & Crossplane · 13 min read

Software Templates: the golden path as a form

In plain words

A Software Template is like a flat-pack furniture kit with instructions. You choose the size and colour on a short form, and the kit is cut, assembled and delivered to your room, with a label saying who owns it. The kit always comes out the same way, so nobody ever forgets the screws that hold it safely to the wall.

Software Templates: the golden path as a form

The catalog tells you what exists. Software Templates create new things the right way: the developer fills in a short form ("name", "owner"), and the scaffolder renders a skeleton repository, pushes it to the git server and registers it in the catalog. This is where a golden path becomes a button.

A template is itself a catalog entity, of kind Template, in scaffolder.backstage.io/v1beta3:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: java-service
  title: Java service
  description: A Spring Boot service with CI, a bucket and docs
spec:
  owner: group:default/platform-team
  type: service
  parameters:
    - title: Service
      required: [name, owner]
      properties:
        name:
          title: Name
          type: string
          pattern: '^[a-z0-9-]+$'
          description: Lowercase, digits and dashes - it becomes the repository and the catalog name
        owner:
          title: Owner
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
  steps:
    - id: fetch
      name: Fetch skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
    - id: publish
      name: Publish
      action: publish:gitlab
      input:
        repoUrl: git.lab?owner=apps&repo=${{ parameters.name }}
        defaultBranch: main
    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}

Three parts:

  • parameters: one or more pages of a form, written as JSON Schema (type, required, pattern, enum), plus ui: hints for the frontend (ui:field: OwnerPicker, EntityPicker, RepoUrlPicker). The schema is checked again on the backend when the task is created: a value that does not match is refused with 400 before anything runs.
  • steps: actions that run in order. Inputs are templated with ${{ }} expressions (Nunjucks): parameters.x, steps.<id>.output.y, and filters such as parseRepoUrl and lower.
  • output: links shown when the task finishes.

The built-in actions you will use

ActionDoesOutput
fetch:templatecopies a skeleton directory into the task's workspace, rendering ${{ values.x }} in file contents and names-
fetch:plaincopies files without templating-
publish:gitlab (module scaffolder-backend-module-gitlab)creates the repository and pushes the workspace as the first commitremoteUrl, repoContentsUrl, projectId, commitHash
publish:github (module scaffolder-backend-module-github)the same on GitHubremoteUrl, repoContentsUrl
catalog:registerregisters the new catalog-info.yamlentityRef, catalogInfoUrl
debug:logwrites a message to the task log-

A note on templating: in the template the values come from parameters; in the skeleton (rendered by fetch:template) they come from values - only what the step passed in its values: input. A skeleton that uses ${{ values.team }} while the step only passes name and owner renders an empty string, not an error.

A skeleton catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  annotations:
    gitlab.com/project-slug: apps/${{ values.name }}
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner }}

repoUrl uses the format the RepoUrlPicker produces: <host>?owner=<group>&repo=<name>. The host must have an integration in app-config.yaml (integrations.gitlab: - host: git.lab); otherwise the step fails with No matching integration configuration for host <host>, please check your integrations config. Note publish:gitlab's default branch is master unless you set defaultBranch.

Running a template

From the UI: Create > choose the template > fill in the form > the task page shows each step's log live. From the API (what the console does for you):

curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"templateRef":"template:default/java-service","values":{"name":"billing-api","owner":"team-billing"}}' \
  http://backstage.lab:7007/api/scaffolder/v2/tasks

The answer is {"id":"<task id>"}. The task runs in the background; read its log:

$ curl -s -H "Authorization: Bearer $TOKEN" http://backstage.lab:7007/api/scaffolder/v2/tasks/$ID/events | jq -r '.[].body.message'
Starting up task with 3 steps
Beginning step Fetch skeleton
Fetching template content from remote URL
Listing files and directories in template
Processing 2 template files/directories with input values
Writing file README.md to template output path with mode 33188.
Writing file catalog-info.yaml to template output path with mode 33188.
Template result written to /tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f
Finished step Fetch skeleton
Beginning step Publish
Creating repo billing-api in namespace apps.
Init git repository {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f}
Adding file {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,filepath=.}
Committing file to repo {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,message=Initial commit}
Pushing directory to remote {dir=/tmp/e16c712d-1e12-49e5-af63-fc3487eb8e1f,remote=origin}
Finished step Publish
Beginning step Register
Registering https://git.lab/apps/billing-api/-/blob/main/catalog-info.yaml in the catalog
Finished step Register
Run completed with status: completed

(mode 33188 is the file mode in decimal: octal 100644, a regular file, rw-r--r--.)

A value that breaks the parameter schema never starts a task:

$ curl -s ... -d '{"templateRef":"template:default/java-service","values":{"name":"Billing API","owner":"team-billing"}}' .../v2/tasks | jq -c '.errors[].stack'
"instance.name does not match pattern \"^[a-z0-9-]+$\""

When a step fails half way

A task is not a transaction. Steps that finished stay done. Two failures every platform team meets:

The repository already exists. Running the same template twice with the same name: publish:gitlab stops with ConflictError: Repository 'billing-api' already exists in namespace 'apps'. Nothing is overwritten - choose another name, or delete the half-made repository first.

The entity is broken. catalog:register first adds the location for real, then asks the catalog to process it as a dry run to find the new entity's name. If the rendered catalog-info.yaml is invalid, the dry run fails and the step ends with:

ResponseError: Request failed with 400 Bad Request

That message hides the cause - the catalog's error is in the response body, not in the task log. And the location stays registered, pointing at a file the catalog keeps rejecting. To see why, dry-run the location yourself (or validate the entity), fix the file in the repository, and let the catalog re-read it. Then fix the template, or the next developer gets the same broken entity.

Testing templates before your users do

  • Keep templates in a git repository with merge requests, like code.
  • Every parameter that becomes a name gets a pattern; every field the skeleton uses is passed in values:.
  • Render the skeleton's catalog-info.yaml with test values and POST it to /api/catalog/validate-entity in CI.
  • Backstage's template editor (reached from the Create page) dry-runs a template through the scaffolder's /v2/dry-run endpoint: the steps run without side effects (actions that do not support dry-run are skipped).

In an interview: a Software Template is a catalog entity with parameters (a JSON Schema form, validated again on the backend), steps (actions such as fetch:template, publish:gitlab / publish:github, catalog:register, templated with ${{ }}) and output links; the scaffolder runs it as a task. Steps are not transactional, and catalog:register leaves the location behind when the entity is invalid.

Why it helps

Templates are where a golden path becomes a button, and also where a platform team's small mistakes multiply: a missing pattern creates bad repositories, a skeleton using the wrong value registers broken entities. Knowing how parameters, steps, outputs and the task log work, and that steps are not transactional, lets you build templates that hold up and debug the failed runs teams bring you.

Commands in this lesson

curl

FAQ

Where are template parameters validated?

In the frontend form and again on the backend when the task is created. The backend checks the values against the parameter JSON Schema and refuses invalid ones with 400 before any step runs, so a pattern on every value that becomes a name is the cheapest safety net.

What is the difference between parameters and values?

In the template, expressions read parameters and step outputs. In the skeleton rendered by fetch:template, expressions read values, which contain only what the step passed in its values input. Anything else renders as an empty string, not an error.

Why did catalog:register fail with 400 Bad Request?

It registers the location first and then dry-runs it to find the new entity. If the rendered catalog-info.yaml is invalid, the dry run fails with that message, which hides the cause. Dry-run the location yourself to see the catalog's real error.

What is left behind when a task fails half way?

Everything the finished steps did: a repository from the publish step and a registered location from catalog:register. Steps are not transactional, so a retry with the same name fails because the repository already exists until you clean up.

How do I run a template without the UI?

POST the template reference and values to /api/scaffolder/v2/tasks, which returns a task id, then read /api/scaffolder/v2/tasks/<id>/events for the step log. That is exactly what the Create page in the portal does for you behind the form.

In an interview Mid

How do Backstage Software Templates work?

A Template is a catalog entity with parameters (a JSON Schema form, validated again on the backend), steps that run actions such as fetch:template, publish:gitlab or publish:github and catalog:register, templated with expressions, and output links. The scaffolder runs it as a task with a log. Steps are not transactional: a failure leaves the repository and the location behind, and catalog:register reports an invalid entity only as 400 Bad Request, so I dry-run the location to find the cause.

Also asked: What does fetch:template do? · How would you test a template in CI? · What happens if you run the same template twice?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.