Template Generator

Authoring templates for Backstage can be a tedious task. On top of the complexity of the dealing with placeholders, Backstage templates include additional steps for publishing the generated code to SCM, registering the component in the catalog, etc.

To help developers / platform engineers to quickly create and test their templates this extension provide a template generator. The generator reverse engineers the template from an existing Quarkus application.

The generator can be use in the following ways:

  • Enabled as part of the build

  • Using the CLI

  • Using the Dev UI

Generating the template at build time

To generate the template at build time, add the quarkus-backstage extension to the project.

<dependency>
    <groupId>io.quarkiverse.backstage</groupId>
    <artifactId>quarkus-backstage</artifactId>
    <version>${quarkus-backstage.version}</version>
</dependency>

Alternatively, the extension can be added using the CLI:

quarkus ext add quarkus-backstage

The feature is disabled by default and can be enabled using the following property:

quarkus.backstage.template.generation.enabled=true

The generated template is placed under the .backstage/templates directory.

generate template using the build

When used in conjunction with the [Dev Service], the generated template can be automatically installed using the property:

quarkus.backstage.devservices.template.installation.enabled=true

Generating the template using the CLI

The template can be generated using the CLI without requiring the extension to be added to the project. This requires that the quarkus-backstage CLI plugin is added to the Quarkus CLI (see [Using the CLI](#using-the-cli)).

quarkus backstage template generate

Generating the template using the Dev UI

When the quarkus-backstage extension is added to the project, A Backstage card will be available in the Dev UI (http://localhost:8080/q/dev-ui). The card will include a link to the template generator, that works similarly to the CLI.

Content of the generated template

Steps

Each generated template includes the following steps:

  • render: Render the project template.

  • publish: Publish the generated code to the remote repository.

  • register: Register the component in the backstage catalog.

Parameters

The parameters of the template include: - componentId: The component id that is used in the backstage catalog - groupId: The group id of the project - artifactId: The artifact id of the project - version: The version of the project - description: The description of the project - name: The name of the project - package: The base package of the project

Skeleton

The skeleton of the project includes: - build files (e.g. pom.xml, build.gradle etc) - the src directory - the catalog-info.yaml - .argocd directory (if argocd is available) - .helm directory (if helm is available) - .kubernetes directory (if kubernetes is available) - openapi.yaml (if available)

Note: Kubernetes and Helm do not output generated files in the project root, but use the kubernetes and helm directories under the build output directory instead. However, when quarkus-backstage is added to the project, the output directories change (for git ops friendliness).

Additional Template Configuration Options

The following sections describe additional configuration options that are available for template generation

Endpoints

It is often desirable to optionally include extensions in the project that expose additional endpoints. This is a great use case for using Template parameters to control the inclusion of these extensions. The template generator allows generating and using parameters for the following endpoints:

  • Health

  • Metrics

  • Info

The endpoints can be configured using the following properties:

quarkus.backstage.template.parameters.endpoints.health.enabled=true
quarkus.backstage.template.parameters.endpoints.metrics.enabled=true
quarkus.backstage.template.parameters.endpoints.info.enabled=true

When the template is generated using the CLI, the following options are available:

  • --health-endpoint

  • --metrics-endpoint

  • --info-endpoint

Helm Values

When the project uses Helm, the values are exposed as parameters in the template. Specifically, a new configuration parameter is added to the template containing properties that correspond to the values in the values.yaml file. The feature can be disabled using the following property:

quarkus.backstage.template.parameters.helm.enabled=true

ArgoCD Configuration

When the project uses ArgoCD, the configuration is exposed as parameters in the template. Specifically, the instance, namespace and path are exposed as parameters in the template.

The feature can be disabled using the following property:

quarkus.backstage.template.parameters.argo-cd.enabled=true

When the template is generated using the CLI, the following options are available: To completely disable the ArgoCD step in the template, use the following property:

quarkus.backstage.template.steps.argo-cd.enabled=true

Note: Dev Templates do not include the ArgoCD step (its removed during the Devification process).