These are the release notes for the v1.41.0 release of Backstage.
A huge thanks to the whole team of maintainers and contributors as well as the amazing Backstage Community for the hard work in getting this release developed and done.
Highlights
BREAKING: Catalog Backend 3.0 - New Defaults
This major release of the catalog plugin backend switches the default value of a number of different flags that affect the behavior of the catalog.
#30546
catalog.orphanStrategy is now delete by default
This switches the default orphan strategy to eagerly delete entities that are no longer referenced within the catalog.
This flag has been suggested many times as a way to clean up entities that have been moved or deleted, and we’re feeling that it’s a good time to turn this on by default.
You can opt back into the previous behavior by supplying orphanStrategy: keep in config.
catalog.orphanProviderStrategy is now delete by default
This switches the default provider installation strategy to no longer keep around entities from providers that are no longer present.
If you have had providers installed in the past that ingested entities into the catalog that you want to keep, the recommendation is to add the provider back to the catalog. If you don’t want the provider to run, you can schedule it with a very large interval.
catalog.disableRelationsCompatibility enabled by default
Relations compatibility is now disabled by default. It can be re-enabled with the new enableRelationsCompatibility flag, but be aware that this significantly reduces overall performance of the catalog.
Relations compatibility ensures that catalog responses contain both targetRef and target within the relations objects, while if it is disabled, only targetRef will be present. The target has not been needed within the Backstage ecosystem for a long time, as the move to targetRef was rolled out many years ago. Therefore, only bespoke external consumers of the catalog should be affected by this change.
catalog.stitchingStrategy is now { mode: 'deferred' } by default
Stitching is the final phase of ingesting entities into the catalog. It collects all information related to an individual entity, generates the full output version of the entity, and writes it to the tables that power the read API.
This switches the stitching to happen async in a background task, rather than in the main catalog processing loop. This makes stitching a lot more performant in large catalogs.
catalog.useUrlReadersSearch always enabled
The catalog.useUrlReadersSearch flag that was added in 1.36 has been removed and is now always enabled. This means that the UrlReaderProcessor in the catalog will always use the search method when reading locations, rather than read. This allows each individual URL reader to decide whether location refers to a single file, or if it’s a wildcard that needs searching.
This breaking change only affects those that have installed custom URL readers for use by the catalog. If these readers already implement a search method that is able to read from exact locations, you’re all set, otherwise you will want to update it roughly as follows:
search(url, options) {
if (!isWildcard(url)) {
return this.readUrl(url, options)
}
// existing search logic, or throw if wildcards aren’t supported
}Contributed by @tcardonne in #29788
BREAKING: Scaffolder Permissions Changes
Some of the alpha permissions rules in the scaffolder have had some potentially breaking changes.
Retrying a task now requires both scaffolder.task.read and scaffolder.task.create permissions, replacing the previous requirement of scaffolder.task.read and scaffolder.task.cancel.
Added a new scaffolder rule isTaskOwner for scaffolder.task.read and scaffolder.task.cancel to allow for conditional permission policies such as restricting access to tasks and task events based on task creators.
And we’ve converted scaffolder.task.read and scaffolder.task.cancel into Resource Permissions.
Contributed by @04kash in #29202
Renaming Canon to Backstage UI
We have decided to rename Canon, the new design system for Backstage, to Backstage UI. For more context on this change, see this comment on the design system RFC. As part of this change, @backstage/canon is being renamed to @backstage/ui, and [canon.backstage.io](http://canon.backstage.io/) is being switched to ui.backstage.io.
Auto backstage:^ version with Backstage Yarn Plugin
Fixed a bug that would prevent yarn from installing new Backstage dependencies with the backstage:^ protocol. 🎉
Contributed by @eipc16 in #30390
Security Fixes
This release does not contain any security fixes.
Upgrade path
We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for keeping Backstage updated.
Links and References
Below you can find a list of links and references to help you learn about and start using this new release.
- Backstage official website, documentation, and getting started guide
- GitHub repository
- Backstage's versioning and support policy
- Community Discord for discussions and support
- Changelog
- Backstage Demos, Blog, Roadmap and Plugins
Sign up for our newsletter if you want to be informed about what is happening in the world of Backstage.