Understanding KDE Templates: Creation, Onboarding and Usage
Adrian Doroiman
Associate Director, Software Architecture
TLDR for quick links. More generic information about Backstage templates is in the main body of this page.
Contents
Introduction to KDE Templates
KDE templates are a foundational component within the Backstage developer portal - which KDE uses as a framework, designed to standardize and accelerate the creation of new software components, services, or resources. By leveraging templates, organizations can ensure consistency, enforce best practices, and streamline onboarding for new projects or teams.
A KDE template defines a repeatable process for generating new entities—such as microservices, libraries, or documentation sites—based on predefined configurations and scaffolding logic. This approach not only reduces manual setup time but also helps maintain compliance with architectural and operational standards across the organization.
Templates are typically authored in YAML and can include input parameters, validation rules, and automation steps. When a user initiates a template, Backstage guides them through a form-driven workflow, collects the necessary information, and then executes the template logic to provision the new resource.
Prerequisites for Creating a New KDE Template
Before creating a new KDE template, it is important to ensure that certain prerequisites are met to facilitate a smooth and effective template development process.
- Access to a KDE Instance: You must have access to a running KDE instance with the necessary permissions to add or modify templates.
- Familiarity with YAML: Backstage templates are typically defined in YAML format. Understanding YAML syntax is essential for authoring and configuring templates.
- Knowledge of Organizational Standards: Be aware of Kyndryl’s best practices, naming conventions, and compliance requirements to ensure the template aligns with internal guidelines.
- Source Code Repository: A GitHub repository is required to store and manage the template files and any associated scaffolding logic.
- Template Inputs and Outputs: Clearly define the parameters and expected outputs for the template to ensure it meets the intended use cases.
- Testing Environment: Access to a test environment is recommended for validating the template before deploying it to production.
.
Template Structure
When starting development of a new template, the minimum that is required is a template.yaml file. A simple template.yaml definition is shown below
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
# some metadata about the template itself
metadata:
name: v1beta3-demo
title: Test Action template
description: scaffolder v1beta3 template demo
spec:
owner: backstage/techdocs-core
type: service
# these are the steps which are rendered in the frontend with the form input
parameters:
- title: Fill in some steps
required:
- name
properties:
name:
title: Name
type: string
description: Unique name of the component
ui:autofocus: true
ui:options:
rows: 5
- title: Choose a location
required:
- repoUrl
properties:
repoUrl:
title: Repository Location
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com
# here are the steps that are executed in series in the scaffolder backend
steps:
- id: fetch-base
name: Fetch Base
action: fetch:template
input:
url: ./template
values:
name: ${{ parameters.name }}
- id: fetch-docs
name: Fetch Docs
action: fetch:plain
input:
targetPath: ./community
url: https://github.com/backstage/community/tree/main/backstage-community-sessions
- id: publish
name: Publish
action: publish:github
input:
description: This is ${{ parameters.name }}
repoUrl: ${{ parameters.repoUrl }}
defaultBranch: 'main'
- id: register
name: Register
action: catalog:register
input:
repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
catalogInfoPath: '/catalog-info.yaml'
Onboarding a Template into KDE
Onboarding a template into Backstage involves registering the template so it becomes available for use within the Backstage developer portal. This process ensures that the template is discoverable, properly configured, and ready to be used by teams to scaffold new projects or resources.
- Template Registration: Add the template’s YAML definition to the KDE catalog, typically by placing the template file in a version-controlled repository and referencing its location in the KDE configuration.
- Catalog Refresh: Trigger a catalog refresh or reload so KDE detects and indexes the new template. This step makes the template visible in the Software Templates section of the portal.
- Template Metadata: Ensure the template includes all required metadata, such as name, description, owner, and input parameters. This information helps users identify and select the appropriate template for their needs.
- Validation and Testing: Before making the template broadly available, test it in a staging or development environment to confirm that it works as intended and aligns with organizational standards.
- Documentation: Provide clear documentation and usage instructions, either embedded within the template or as a separate resource, to guide users through the template’s workflow and requirements.
Once onboarded, the template can be used by teams to quickly and consistently generate new components, ensuring alignment with best practices and reducing manual setup effort.
Step-by-Step Guide to Using a Newly Onboarded KDE Template
Applying a new KDE Template involves a series of guided steps within the KDE portal. The process is designed to be intuitive and ensures that all necessary information is collected and validated before the template is executed.
- Access the Component Creation Page: Navigate to the Software Templates section, typically available at /create in your KDE instance. For local development, this is often http://localhost:3000/create.
- Select a Template: Browse the available templates and choose the one that matches your intended use case. Each template may have a unique set of input requirements.
- Provide Input Variables: Fill in the required variables as prompted. These may include project name, description, owner, and other parameters specific to the template.
- Specify Backstage Metadata: Enter additional fields required for KDE usage, such as the owner
- Run the Template: After confirming all inputs, initiate the component creation process. A live progress popup will display the status of each step. If any step fails, you can review logs for troubleshooting.
- Cancel if Needed: You can cancel the process at any time. If you do, an abort signal is sent, and subsequent steps will not be executed. The current step will only be cancelled if supported.
- View the Created Component: Once the template completes successfully, use the "View in Catalog" button to access the newly registered component in the Backstage catalog.
This workflow ensures that new components are created efficiently, with all necessary metadata and organizational standards applied from the outset.
Best Practices and Troubleshooting Tips
Adhering to best practices when working with Backstage templates ensures a smooth experience for both template authors and users. Additionally, being aware of common troubleshooting steps can help resolve issues quickly and maintain template reliability.
- Keep Templates Modular: Design templates to be modular and reusable, allowing teams to adapt them for various use cases without duplicating logic.
- Document Inputs and Outputs: Clearly document all required input parameters and expected outputs within the template and supporting documentation to minimize user confusion.
- Validate Early and Often: Use validation rules in the template to catch missing or incorrect input values before execution begins.
- Test in a Development Environment: Always test new or updated templates in a non-production environment to ensure they function as intended and comply with organizational standards.
- Version Control: Store templates in a version-controlled repository to track changes, facilitate collaboration, and enable rollback if issues arise. By convention, you should store each template in its own repository.
- Monitor Execution Logs: Encourage users to review execution logs for each template run. Logs provide valuable insights into failures and can help pinpoint the root cause of issues.
- Provide Troubleshooting Guidance: Maintain a troubleshooting guide that addresses common errors, such as missing permissions, incorrect repository URLs, or failed automation steps.
- Engage with the Community: Participate in the Backstage community forums and discussions to stay updated on best practices, new features, and solutions to common challenges.