Make Your Backstage Templates Resilient

I suppose that you are a user of Backstage and have your own templates that automate some repetitive and/or complicated flows of your organization. Some of your templates take a long time to be executed. For example, you provision your infrastructure, and your template guards the process along the way. Now, you are happy that you provided your engineers with these templates to lessen their burden, but you have to be careful with redeploying Backstage because you might fail ongoing tasks and make your engineers angry.

Here, I’ll explain what actions you can follow from release v1.23.0-next.0 to make your templates resilient to redeployment or any accidental server failures.

Steps

Since release v1.23.0-next.0 (or you can wait for a monthly release 1.23.0, which will happen at the end of February), you can mark your templates as recoverable, but you have to be sure that all your actions are idempotent. That means that your action can be running multiple times and having the same result as being called once. 

Let’s go step by step what you have to do:

1. Enable recoverability in your app-config-local.yaml file:

scaffolder:
   EXPERIMENTAL_recoverTasks: true

2. Open your template which you would like to make recoverable and there, add EXPERIMENTAL_recovery config as follows:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: docs-mocks-idempotent-template
  title: Documentation Mock Idempotent running Template
  description: Create a new standalone documentation project
  tags:
    - recommended
    - techdocs
    - mkdocs
spec:
  owner: backstage/techdocs-core
  type: documentation
  lifecycle: experimental
  EXPERIMENTAL_recovery:
    EXPERIMENTAL_strategy: 'startOver'

At the moment, only the startOver strategy is supported. To switch it off, you can remove the EXPERIMENTAL_recovery block or provide the value 'none'.

3. Make each of your actions idempotent. Let's assume your template is simplistic and has the following actions inside:

  steps:
    - id: fetch
      name: Template Docs Skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          destination: ${{ parameters.repoUrl | parseRepoUrl }}
          owner: ${{ parameters.owner }}
    - id: publish
      name: Publish
      action: publish:github
      input:
        allowedHosts: [ "github.com" ]
        description: This is ${{ parameters.name }}
        repoUrl: ${{ parameters.repoUrl }}
    - id: register
      name: Register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: "/catalog-info.yaml"

• fetch:template - This will be idempotent for your case, as at this moment, Backstage doesn't preserve the workspace; on each run, it will create a new one.
• publish:github - This has to be replaced with your custom action. The modification to this action can look like this:

• catalog:register - This has to be also replaced with your custom action, and inside, prior to registering a new location, check if the location hasn't been registered yet. If yes, skip it, instead of throwing an error.

Give it a try. If you have more complicated templates, most probably you have more of your custom actions than default ones, and you are quite comfortable working with such customizations. 

In future releases, you can find the most used default actions supporting idempotency, but creating more complicated templates will require homework from your side in any case. 

Don't waste your time: start your journey now! Drop your feedback on what you think about it or if you need some more clarification on certain things as to how to make it fly on your end.