@qshift/quarkus-plugins

May 3, 2024 · View on GitHub

This project contains different Backstage plugins to work with Quarkus which is a Kubernetes-native Java framework tailored for GraalVM and HotSpot, crafted from best-of-breed Java libraries and standards.

Prerequisites

Node.js (18 or 20)
nvm, npm and yarn installed

Getting started

To play with one of our plugins, create first a Backstage application locally using this command:

npx @backstage/create-app@latest

Next, verify if the newly application created is working fine: yarn dev

If this is the case, you can start to play with one or all our plugins :-)

Quarkus Console

Before to use the quarkus console, it is needed to install and configure the kubernetes plugin as documented.

Import first the following package within an existing backstage application:

yarn add --cwd packages/app "@qshift/plugin-quarkus-console"

Next, customize the packages/app/src/components/catalog/EntityPage.tsx to include a new <EntityLayout.Route...>:

import {
    QuarkusPage,
} from "@qshift/plugin-quarkus-console";
...
const serviceEntityPage = (
  <EntityLayout>
  ...
    <EntityLayout.Route path="/quarkus" title="Quarkus">
      <QuarkusPage />
    </EntityLayout.Route>

Start backstage, register a quarkus component including the following annotations

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-quarkus-app
  description: A cool quarkus app
  annotations:
    app.kubernetes.io/name: quarkus
    app.quarkus.io/quarkus-version: "3.9"

and open the Quarkus view using the software catalog.

Scaffold template fields

This plugin proposes different UI fields to be used part of a template scaffolded by backstage:

Name	Description
QuarkusExtensionList	Filter, select your Quarkus extensions using the `Quarkus Extension List` field.
QuarkusQuickstartPicker	Select using the `Quarkus QuickStart Picker` one of the quickstarts available: https://github.com/quarkusio/quarkus-quickstarts
QuarkusVersionList	List the recommended and available versions of Quarkus

NOTE: Such frontend feature(s) should be used with the quarkus scaffolder backend plugin !

To use them, import the needed package under the following path within an existing backstage application:

yarn add --cwd packages/app "@qshift/plugin-quarkus"

Next, customize the packages/app/src/App.tsx file according to the field that you plan to use and described hereafter

Local development

When you develop a new <ScaffolderFieldExtensions/>, then we recommend to launch the plugin locally using the createDevApp of the ./dev/index.tsx file for testing/debugging purposes.

To play with it, open a terminal and run the command: yarn start within the ./plugins/quarkus folder

NOTE: Don't forget to open a second terminal and to launch the backend or backend-next there, using yarn start and to specify the locations of the templates to play with !

If your IDE supports to debug an application that is running on the localhost in the development mode like IntelliJ, then use the commands "Command + Shift" and click on the url: http://localhost:3000, next add a breakpoint within your tsx file

Quarkus extensions field

This field allows a user to pick up Quarkus extension(s) from the code generator server.

Edit the packages/app/src/App.tsx file to add the tag of the <QuarkusExtensionListField /> within the tag <Route path="/create" element={<ScaffolderPage />}> as described hereafter.

...
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
import { QuarkusExtensionListField } from '@qshift/plugin-quarkus';
...
    <Route path="/create" element={<ScaffolderPage />}>
      <ScaffolderFieldExtensions>
        <QuarkusExtensionListField />
      </ScaffolderFieldExtensions>
...

Update your template file to use extension field:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: quarkus-application
  title: Create a Quarkus Application
  description: Create a Quarkus application using code generator "code.quarkus.io"
  tags:
    - quarkus
    - java
spec:
  owner: guests
  type: service

  parameters:
  ...
  - title: Customize the Quarkus application features
    properties:
      extensions:
        title: Quarkus Extensions
        type: array
        description: The list of the quarkus extensions
        ui:field: QuarkusExtensionList
  steps:
  ...

When done, you will be able to select your extension(s) when you scaffold a new project.

It is also possible to filter the extensions (aka restrict the list of the extensions to be used):

    ui:field: QuarkusExtensionList
    ui:options:
      filter:
        extensions:
          - io.quarkus:quarkus-resteasy-reactive-jackson
          - io.quarkus:quarkus-smallrye-openapi
          - io.quarkus:quarkus-smallrye-graphql
          - io.quarkus:quarkus-hibernate-orm-rest-data-panache

If you would like to use a different code generator server, set the following property

    ui:field: QuarkusExtensionList
    ui:options:
        codeQuarkusUrl: https://staging.code.quarkus.io

Quarkus Extension List - default (field):

Quarkus Extension List - Select (field):

Quarkus Extension List - Added (field):

Quarkus Quickstart picker field

This field allows a user to pick up a Quarkus Quickstart project.

Edit the packages/app/src/App.tsx file to add the tag of the <QuarkusQuickstartPickerField /> within the <Route path="/create" element={<ScaffolderPage />}> as described hereafter.

...
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
import { QuarkusQuickstartPickerField } from '@qshift/plugin-quarkus';
...
    <Route path="/create" element={<ScaffolderPage />}>
      <ScaffolderFieldExtensions>
        <QuarkusQuickstartPickerField />
      </ScaffolderFieldExtensions>
...

Update your template file to use extension field:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: quarkus-quickstart
  title: Create a Quarkus Application from a Quickstart
  description: Create a Quarkus Application from one of the Quickstarts you can find on "https://github.com/quarkusio/quarkus-quickstarts"
  tags:
    - quarkus
    - java
spec:
  owner: guests
  type: service

  parameters:
  ...
  - title: Select the Quarkus Quickstart
    properties:
      quickstartName:
        title: Quickstart Name
        type: string
        description: The name of the quickstart to clone
        default: 'hibernate-orm-panache'
        ui:field: QuarkusQuickstartPicker
  steps:
  ...

When done, you will be able to create a new Quarkus project from the quickstart selected.

Quarkus Quickstart Picker - default (field):

Quarkus Quickstart Picker - select (field):

Quarkus Version list field

This field allows a user to select a Quarkus version from the list of the recommended and available version.

Edit the packages/app/src/App.tsx file to add the tag of the <QuarkusQuickstartPickerField /> within the <Route path="/create" element={<ScaffolderPage />}> as described hereafter.

...
import { ScaffolderFieldExtensions } from '@backstage/plugin-scaffolder-react';
import { QuarkusVersionListField } from '@qshift/plugin-quarkus';
...
    <Route path="/create" element={<ScaffolderPage />}>
      <ScaffolderFieldExtensions>
        <QuarkusQuickstartPickerField />
      </ScaffolderFieldExtensions>
...

Update your template file to use extension field:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: quarkus-application
  title: Create a Quarkus Application
  description: Create a Quarkus application using code generator "code.quarkus.io"
  tags:
    - quarkus
    - java
spec:
  owner: guests
  type: service

  parameters:
  ...
  - title: Customize the Quarkus application features
    properties:
      quarkusVersion:
      title: Quarkus version
      type: array
      description: The list of the quarkus supported/recommended
      ui:field: QuarkusVersionList
      
  steps:
  ...

When done, you will be able to select the quarkus version to be used to scaffold your quarkus project

Quarkus Version list - Select (field):

Quarkus Version list - Recommended (field):

Quarkus actions

This plugin proposes 2 actions able to:

Action	Description
`quarkus:app:create`	Create a Quarkus using the website `code.quarkus.io` able to generate a zip file of a Quarkus project and extensions selected (using extension list field)
`quarkus:quickstart:clone`	Clone a Quarkus "Quickstart" repository.

To use this plugin, import the following packages under the following path:

yarn add --cwd packages/backend "@qshift/plugin-quarkus-backend"
yarn add --cwd packages/backend "@backstage/integration"

quickstart:clone

To use the Quarkus action able to clone a quarkus quickstart from this repository, then edit the file packages/backend/src/plugins/scaffolder.ts to register the action: cloneQuarkusQuickstart.

Here is a snippet example of code changed

import { ScmIntegrations } from '@backstage/integration';
import {createBuiltinActions, createRouter} from '@backstage/plugin-scaffolder-backend';
import { cloneQuarkusQuickstart } from '@internal/plugin-quarkus-backend';
...
  const integrations = ScmIntegrations.fromConfig(env.config);

  const builtInActions = createBuiltinActions({
    integrations,
    catalogClient,
    config: env.config,
    reader: env.reader,
  });

  const actions = [...builtInActions, cloneQuarkusQuickstart()];

  return await createRouter({
    actions,

The following table details the fields that you can use to use this action:

Input	Description	Type	Required
quickstartName	The name of the quickstart project to be used	string	Yes
groupId	Maven GroupID	No
artifactId	Maven ArtifactID	No
targetPath	Target Path to access the code within the workspace	No
additionalProperties	Quarkus properties	No
database	Quarkus backend database (PostgreSQL, etc)	No
infoEndpoint	Quarkus API endpoint	No
healthEndpoint	Kubernetes Health ednpoint	No
metricsEndpoint	Enpoint exposing the Quarkus metrics	No

Example of action:

  steps:
    - id: template
      name: Generating the Source Code Component
      action: quarkus:quickstart:clone
      input:
        values:
          groupId: ${{ parameters.groupId }}
          artifactId: ${{ parameters.artifactId }}
          version: ${{ parameters.version }}
          quickstartName: ${{ parameters.quickstartName }}
          additionalProperties: ${{ parameters.additionalProperties }}

app:create

To use the Quarkus action able to create a quarkus application using code.quarkus.io, then edit the file packages/backend/src/plugins/scaffolder.ts to register the action: createQuarkusApp.

Here is a snippet example of code changed

import { ScmIntegrations } from '@backstage/integration';
import {createBuiltinActions, createRouter} from '@backstage/plugin-scaffolder-backend';
import { createQuarkusApp } from '@internal/plugin-quarkus-backend';
...
  const integrations = ScmIntegrations.fromConfig(env.config);

  const builtInActions = createBuiltinActions({
    integrations,
    catalogClient,
    config: env.config,
    reader: env.reader,
  });

  const actions = [...builtInActions, createQuarkusApp()];

  return await createRouter({
    actions,

The following table details the fields that you can use to use this action:

Input	Description	Type	Required
quarkusVersion	Quarkus version	string	No
groupId	Maven GroupID	string	No
artifactId	Maven ArtifactID	string	No
version	Maven Version	string	No
buildTool	Tool to be used to build: 'MAVEN', 'GRADLE', 'GRADLE_KOTLIN_DSL'	string	No
extensions	List of the Quarkus extensions	array	No
javaVersion	JDK version	string	No
starterCode	Generate for the project some code to start ?	boolean	No
targetPath	Target Path to access the code within the workspace	string	No
additionalProperties	Quarkus properties	string	No
database	Quarkus backend database (PostgreSQL, etc)	string	No
infoEndpoint	Has a Quarkus API endpoint ?	boolean	No
healthEndpoint	Has a Kubernetes Health endpoint ?	boolean	No
metricsEndpoint	Has a Quarkus metrics endpoint ?	boolean	No

Example of action:

  steps:
    - id: template
      name: Generating the Source Code Component
      action: quarkus:app:create
      input:
        values:
          quarkusVersion: ${{ parameters.quarkusVersion[0] }}
          groupId: ${{ parameters.groupId }}
          artifactId: ${{ parameters.artifactId }}
          version: ${{ parameters.version }}
          buildTool: ${{ parameters.buildTool }}
          javaVersion: ${{ parameters.javaVersion }}
          extensions: ${{ parameters.extensions }}
          database: ${{ parameters.database }}
          infoEndpoint: ${{ parameters.infoEndpoint }}
          healthEndpoint: ${{ parameters.healthEndpoint }}
          metricsEndpoint: ${{ parameters.metricsEndpoint }}
          additionalProperties: ${{ parameters.additionalProperties }}
          starterCode: true