Skip to content

Commit e069326

Browse files
aliokaliok
authored
Merge pull request #117 from aliok/2025-01-02-backstage-templates
Document Backstage Knative Function templates
2 parents dc0126a + eebf1e0 commit e069326

File tree

2 files changed

+146
-0
lines changed

2 files changed

+146
-0
lines changed

‎modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414
*** xref:serverless:serving/serving-with-ingress-sharding.adoc[Use Serving with OpenShift ingress sharding]
1515
*** xref:serverless:serving/scaleability-and-performance-of-serving.adoc[Scalability and performance of {serverlessproductname} Serving]
1616
*** xref:serverless:serving/serving-transport-encryption.adoc[Serving Transport Encryption]
17+
** Functions
18+
*** xref:serverless:functions/backstage-templates.adoc[Backstage Templates for Knative Functions]
1719
* Serverless Logic
1820
** xref:serverless-logic:about.adoc[About OpenShift Serverless Logic]
1921
** xref:serverless-logic:release-notes.adoc[Release notes]

‎modules/serverless/pages/functions/backstage-templates.adoc‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
= Setup Backstage Templates for Knative Functions
2+
:compat-mode!:
3+
// Metadata:
4+
:description: Setup Backstage Templates for Knative Functions in {serverlessproductname}
5+
6+
This page describes how to set up Backstage Templates for Knative Functions in {serverlessproductname}, which allow you to create Knative Functions easily in Backstage.
7+
8+
These function templates are provided as examples to help you get started with Knative Functions. You should customize these templates to suit your needs.
9+
10+
== Anatomy of a Knative Function Template
11+
12+
A Knative Function template is a YAML file that specifies the structure of a Backstage template. For more information about Backstage templates, see https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/customizing/configuring-templates[Red Hat Developer Hub documentation].
13+
14+
Knative community provides a https://github.com/knative-extensions/backstage-plugins/blob/main/backstage/templates/location.yaml[Backstage `Location`] where there are multiple templates available. You can use these templates to create Knative Functions in Backstage.
15+
16+
An example of a Knative Function template is as follows, for a Go HTTP function:
17+
18+
[source,yaml]
19+
----
20+
apiVersion: scaffolder.backstage.io/v1beta3
21+
kind: Template
22+
metadata:
23+
name: knative-func-go-http <1>
24+
title: Create a go http Knative Function application with a CI pipeline <2>
25+
description: Create a go http Knative Function application with a CI pipeline
26+
tags:
27+
- go
28+
- http
29+
- knative
30+
- func
31+
spec:
32+
owner: knative-authors
33+
system: knative
34+
type: service
35+
36+
parameters: <3>
37+
- title: Provide information about the new component
38+
required:
39+
- orgName
40+
- repoName
41+
- owner
42+
- system
43+
properties:
44+
orgName:
45+
title: Organization Name
46+
type: string
47+
repoName:
48+
title: Repository Name
49+
type: string
50+
description:
51+
title: Description
52+
type: string
53+
description: Help others understand what this component is for
54+
owner:
55+
title: Owner
56+
type: string
57+
ui:field: EntityPicker
58+
ui:options:
59+
catalogFilter:
60+
kind:
61+
- Group
62+
- User
63+
system:
64+
title: System
65+
type: string
66+
ui:field: EntityPicker
67+
ui:options:
68+
catalogFilter:
69+
kind:
70+
- System
71+
steps:
72+
- id: sourceCodeTemplate <4>
73+
name: Generating the Source Code Component
74+
action: fetch:template
75+
input:
76+
url: ./skeletons/go-http/
77+
values:
78+
orgName: ${{ parameters.orgName }}
79+
repoName: ${{ parameters.repoName }}
80+
owner: ${{ parameters.owner }}
81+
system: ${{ parameters.system }}
82+
83+
- id: catalogTemplate <5>
84+
name: Generating the Catalog Info Component
85+
action: fetch:template
86+
input:
87+
url: ./catalog-info/
88+
values:
89+
orgName: ${{ parameters.orgName }}
90+
repoName: ${{ parameters.repoName }}
91+
owner: ${{ parameters.owner }}
92+
system: ${{ parameters.system }}
93+
94+
- id: publish <6>
95+
name: Publishing to the Source Code Repository
96+
action: publish:github
97+
input:
98+
allowedHosts: [ 'github.com' ]
99+
description: ${{ parameters.description }}
100+
repoUrl: github.com?owner=${{ parameters.orgName }}&repo=${{ parameters.repoName }}
101+
defaultBranch: main
102+
103+
- id: register <7>
104+
name: Registering the Catalog Info Component
105+
action: catalog:register
106+
input:
107+
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
108+
catalogInfoPath: /catalog-info.yaml
109+
110+
output: <8>
111+
links:
112+
- title: Open the Source Code Repository
113+
url: ${{ steps.publish.output.remoteUrl }}
114+
- title: Open the Catalog Info Component
115+
icon: catalog
116+
entityRef: ${{ steps.register.output.entityRef }}
117+
----
118+
<1> The unique name of the template.
119+
<2> The title of the template, which is shown to users.
120+
<3> The parameters that the user must provide when creating a new component from this template.
121+
<4> The first step in the template, which generates the source code for the function. It uses the source code in https://github.com/knative-extensions/backstage-plugins/tree/main/backstage/templates/skeletons/go-http[`./skeletons/go-http/` directory relative to the template location] as the code skeleton.
122+
<5> This step generates the catalog info for the function. This catalog info is used to register the function in the Backstage catalog.
123+
<6> This step publishes the source code to the source code repository. You must have the GitHub integration set up to use this step. See https://docs.redhat.com/documentation/en-us/red_hat_developer_hub/1.4/html-single/authentication/index#assembly-auth-provider-github[Red Hat Developer Hub documentation] for more information.
124+
<7> This step registers the function in the Backstage catalog.
125+
<8> The output of the template, which includes links to the source code repository and the catalog info component. This output is shown to the user after the template is executed.
126+
127+
For more information about the structure of a Backstage template, see https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/customizing/configuring-templates#proc-adding-templates_configuring-templates[Red Hat Developer Hub documentation].
128+
129+
== Add Knative Function Templates to Backstage
130+
131+
To add Knative Function templates to Backstage, you must follow the instructions in the https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.4/html/customizing/configuring-templates#proc-adding-templates_configuring-templates[Red Hat Developer Hub documentation].
132+
133+
The `Location` provided by Knative community is at https://github.com/knative-extensions/backstage-plugins/blob/main/backstage/templates/location.yaml. You can use this location to add Knative Function templates to Backstage.
134+
135+
== Using the templates
136+
137+
. Instantiate the template in Backstage.
138+
. Clone the repository.
139+
+
140+
[source,bash]
141+
----
142+
$ git clone <repository-url>
143+
----
144+
. In the cloned repository, the `kn` command will be working with the function instance. To learn more about the `kn` command, see https://docs.openshift.com/serverless/1.34/cli_tools/functions_cli/kn-functions.html[{product-name} documentation].

0 commit comments

Comments
 (0)