From Raw YAML to Ready-to-Use: Rebuilding Our Backstage Integration for Platform Adoption
TL;DR: Syntasso Kratix Enterprise (SKE) now automatically generates Backstage Software Templates and catalog entities from your Kratix Promises. We've redesigned this out-of-the-box Backstage experience. Request forms are clearer, users pick a Backstage Group instead of a Kubernetes Namespace, and they get immediate "Pending" feedback after submitting. New Promise and Resource pages show health, status and provisioning progress at a glance, so platform users can find, request and track services without reading YAML.
Where we started: Backstage Software Templates generated from Kratix Promises
We at Syntasso are very proud of the SKE-Backstage integration we built. You apply a Promise, you get a Component and a Template automagically appearing on your Backstage instance.
You can send requests to the platform via GitOps or directly via the Kubernetes API. Changes to the Promise regenerate the Template. You can use an array of CRD properties to control the validation applied to the form; you can run custom containers to customise what the platform generates.
It is great.
Except, it kinda looks like this:
Which is enough to get you started, but it won’t necessarily wow the platform users. It solved the immediate problem for the platform engineer (how do I expose this service on Backstage), but it was quite simple on the visual front (apparently raw YAML is not everyone’s cup of tea… not sure why).
In this blog, we will explore why the interface matters and how it can drive adoption of your platform. We'll look at what we had before, what we have learned from our customers, and how we used that learning to improve the out-of-the-box experience with Backstage. We will then look at what we have just released to make it EVEN better.
Why the interface matters for platform adoption
A problem lots of platform teams face in their organisations is adoption: they build a nice, self-contained, fully managed platform, full of amazing services, and… no one uses it. And oftentimes it’s not a lack of functionality. We see this repeatedly with our customers, and some of the commonly raised barriers to adoption are:
Developers don’t know what’s available in the platform
Developers don’t know how to consume and monitor what they requested from the platform
Inertia is strong, and change is hard
This is where we see portals like Backstage and Cortex really help. A platform can be technically excellent and still fail to gain adoption if it asks users to work in unfamiliar ways. A portal like Backstage turns those capabilities into discoverable and contextual artefacts: you have services, owners, environment lifecycles, request forms, and documentation, all in one centralised place. Users can go through a wizard-like experience and request what they need, and quickly understand when things go wrong.
"What are you talking about, developers really want clear APIs, CLIs, and ways to use things with AI. GUIs are not it."
Hear me out, I’m right there with you. Your users will only use your platform if they can successfully integrate it with their existing workflows, and that often means making it programmable and accessible via APIs. They will need CLI tools and MCP servers so their agents can consume the services. That’s all true.
But as much as I love writing YAML, and as much as I find kubectl very simple to use, they may not be the best tools to get people started.
"Ah but we have a GitOps flow that you can PR to a repository and…"
Sure. I’m certain it’s great. But it adds more cognitive load for the platform user than clicking buttons, especially when she has many other things on her mind and just wants access to the service she needs. GUIs are familiar, and recognition rather than recall is an important aspect of making systems more accessible.
Portals do not replace APIs, CLIs, GitOps, etc. They complement them. A portal can provide the easiest path into the platform, while more experienced users and automated systems continue to use the interfaces that best fit their workflows.
What our original Backstage integration looked like (and where developers got stuck)
From the three barriers we discussed, our previous integration solved only the service discovery challenge: a Promise is installed, the Backstage Template is generated, and users can find the services in the Catalog. Users can see both a Component for the Promise, and a Template to create an instance of that Promise:
From the template, they can fill the form, click next, next, next:
And finally, once the request is fulfilled, the user will see a Component for their services, and expand and explore its status:
We can quickly highlight sharp edges from the developer’s point of view:
What is a Namespace? What is the value I should write in there?
The stepper on the Template gives me some Kratix-specific terms I don’t understand. What about the log lines?
I clicked save. Where’s my resource?
On the resource page, things get even more confusing:
Where can I see detailed information about my resource?
What did I even request again?
What is the status of it right now? Is it ready?
Wow, that’s a lot of YAML
Still better than a terminal (maybe?). In our defence, a Backstage expert could make it nicer with all the information that is buried in there, and could customise the Entities with BYO Customisations. However, the platform teams are already responsible for so much; we wanted to make things much better.
The “out-of-the-box Backstage” SKE experience
We named the epic “Out-of-the-box Backstage”. We wanted platform engineers and platform consumers to have a user-ready experience with our integration, with minimal configuration. Ideally, they plug in the Portal Controller, configure the SKE Backstage plugins, and get something that is not only beautiful but also clear and informative.
On the template, we focused on:
Making the language clearer, using terms known to the developers
Providing better error messages and using the right logger for the audience
Pointing the user to the resource they just created
Providing an alternative to the Namespace field, using terminology closer to a Backstage user. For that, we released a feature on our Portal Controller that enables a mapping of Backstage Groups (that users belong to) to Kubernetes Namespaces (either via group name or via a group annotation).
These small changes have already had a big impact on the developer experience: no more guessing what fields mean, no more confusing outputs, and a clear pointer to where to go next.
Since there’s a delay between the user submitting a request and the component for that request being generated by the integration, we are now creating a “Pending” catalog entity for the resource, so the user can get immediate feedback:
The big changes are in the Component pages. Both the Promise and Resource pages received a major revamp. From the Promise page, we wanted the Portal user to be able to see:
Is the Promise currently available?
What is the status and version of the Promise?
Is this a Compound Promise?
How many instances are there of this Promise? Who owns them? At a glance, are the resources healthy?
You can see the changes in the screenshot below:
From there, you can also navigate to the Resource itself. For the resource, we focused on answering these questions:
At a glance, what’s the state of my resource?
What information is available to me about my resource?
Is my resource healthy? If not, what is failing, and why?
What’s the status of the resource provisioning (or update)?
And if it fails at a stage, which one failed?
What’s my raw request?
The resulting changes are all captured in the screenshot below:
As (I hope) you can see from the screenshots above, the out-of-the-box SKE Backstage integration is now much better, and it creates a more compelling experience for your users by tackling the discoverability, usability, and barriers to adoption we discussed earlier.
Of course, you can still customise how SKE generates the Backstage Entities, and hand-craft your Backstage experience to suit your org best, but now you have a better head start.
See our new Backstage integration in action
Your platform can be technically excellent and still go unused if developers can't find what's on offer, request it confidently and see what happened next. With SKE, every Promise you apply becomes a polished, self-service experience in Backstage. There are clear forms, instant feedback, and health and status at a glance, all generated for you. Your platform team doesn't have to hand-craft a single page.
Ready to make your platform the easy choice for developers?
Book a demo to see the new Backstage experience running on a live platform, and talk through how SKE can drive adoption in your organisation.
Read the Portal Controller docs to get set up, or to customise the generated entities for your organisation.
Join the Kratix community to tell us what you think. Do you see other barriers to adoption? Would you rather ship only CLIs? We're curious to hear from you, and your feedback shapes what we build next.
Comments