はじめに
みなさんこんにちは。 Backstage にどっぷり浸かっている ACS事業部亀崎です。
Backstageの主要機能の１つであるSoftware Template、みなさんご利用されていますか？
Software Templateを使うと、リポジトリを作成するタイミングでカタログ情報も一緒に登録することができます。
通常は作成したらテンプレート元と作成されたものの関係はそれで終わり、だったのですが、そのカタログ情報に、「いつSoftware Template」を実行したのか、それはどのテンプレートなのか、バージョンはいつのものかを動的に付与するアクションがcommunity-pluginにありました。
ほんのちょっと情報を付加するアクションですが、実はSoftware Templateの適用ライフサイクルをより改善する機能ともなり得るものなのでご紹介します。
Software Templateのライフサイクルを改善するPlugin
annotation action
それでは今回の主役、『カタログ情報に、いつSoftware Templateを実行したのか、それはどのテンプレートなのか、バージョンはいつのものかを動的に付与するアクション』に登場いただきましょう。
それが annotator action plugin です。
Pluginのドキュメントにも記載がありますが、こちらのPluginを導入すると次のアクションが使えるようになります。
| Action | Description |
|---|---|
| catalog:timestamping | backstage.io/createdAt annotationに現在のタイムスタンプを挿入する |
| catalog:scaffolded-from | spec.scaffoldedFrom に実行しているTemplateの entityRef を挿入する |
| catalog:annotate | 指定した独自のannotationを挿入する |
| catalog:template:version | Templateに記載されているバージョンをbackstage.io/template-version に挿入する |
「いつSoftware Templateを実行したのか」（catalog:timestamping ）、「どのテンプレートを使用したのか」（catalog:scaffolded-from）、「バージョンはいつのものか」（catalog:template:version）がこれらのアクションを使うことで、把握できるようになるというわけです。
実際のテンプレートの例（一部改変）をみてみましょう。
apiVersion: scaffolder.backstage.io/v1beta3 kind: Template metadata: name: create-react-app-template-with-timestamp-entityRef title: Create React App Template description: Create a new CRA website project annotations: backstage.io/template-version: 0.0.1 tags: - react - cra spec: owner: web@example.com type: website parameters: - title: Provide some simple information required: - component_id - owner properties: component_id: title: Name # 〜〜以下 parameters 部省略〜〜 steps: - id: template name: Fetch Skeleton + Template action: fetch:template input: # 〜〜入力値省略〜〜 # タイムスタンプを記載 - id: timestamp name: Add Timestamp to catalog-info.yaml action: catalog:timestamping # catalog-info.yamlにテンプレートバージョンを埋め込み - id: version-templateRef name: Append the version of this template to the entityRef action: catalog:template:version # 実行するテンプレート（＝このテンプレート）のEntityRefを埋め込み - id: append-templateRef name: Append the entityRef of this template to the entityRef action: catalog:scaffolded-from - id: publish name: Publish action: publish:github input: description: This is ${{ parameters.component_id }} repoUrl: ${{ parameters.repoUrl }} repoVisibility: public - id: register name: Register action: catalog:register input: repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }} catalogInfoPath: '/catalog-info.yaml' output: links: - title: Repository url: ${{ steps.publish.output.remoteUrl }} - title: Open in catalog icon: catalog entityRef: ${{ steps.register.output.entityRef }}
こちらを実行すると catalog-info.yaml には以下のような形式で出力されます。
apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: xxxxxxx annotations: backstage.io/createdAt: 12/3/2025, 2:38:46 PM # ★ backstage.io/template-version: 0.0.1 # ★ labels: {} spec: type: service owner: group:default/guests lifecycle: experimental scaffoldedFrom: template:default/create-react-app-template-with-timestamp-entityRef # ★
今回のアクションで挿入された部分は ★印の部分です。
こうした情報が挿入されると何がよいのでしょうか？
その利点は 次の pluginを導入すると現れます。
scaffolder relation catalog processor
scaffolder relation catalog processor は、先程挿入した annotation spec.scaffoldedFrom を活用するカタログ情報プロセッサです。
このPluginには２つの機能があります。1つ目はさきほど挿入した spec.scaffoldedFrom 情報をもとに オリジナルのテンプレートと作成されたカタログ情報との間に relation情報を挿入します。
これにより、Backstageのrelationshipとしてテンプレート元／テンプレート実行先の関係を把握することができるようになります。 以下のようなイメージです。
テンプレート元を中心に表示した場合、そこから生成されたカタログ情報がすべてこの依存関係図から把握することができるようになります。
テンプレート提供側として考えた場合、修正内容を通知したいのだけれど、、、といった状況にも対応することができるようになります。
2つ目の機能が Notification です。こちらの機能は Backstage Notification を利用し、テンプレート元のバージョンが更新されると、そのテンプレートから生成されたリポジトリのカタログ情報に対して（つまりそのカタログ情報のオーナーに）テンプレートが更新されたことを通知します。
通知されたあとどのように対応をするかはそのテンプレートの提供元や利用者が決定する必要がありますが、まずバージョンアップされたということは伝えることができます。
このように、テンプレート実行時にカタログ情報にテンプレート元がどこか、そのバージョンはなにかを設定しておくことで、その後のライフサイクルで変更があった場合の対応につなげることができるようになるのです。
テンプレート機能で作成して終わり、ではなくなるというのは大きな進歩ではないでしょうか。
Community Pluginなどのリポジトリを散策すると「お、これ使えるのでは！？」というようなものが見つかったりします。 ぜひ皆さんもときにはこちらのリポジトリを覗いてみてはいかがでしょうか。
PlaTTのご紹介
このような便利な機能がいくつもあるBackstageですが、必要なPluginを探してそれを導入したり、アップデート等の管理が面倒になりがち。 また、導入して終わりというものでもなく、使い方を探求することでその能力を100％発揮できるようになるものも多いです。 こういうところを１つ１つ解消するのって面倒ではありませんか？ そんな面倒さを解消するのが、私たちが提供するBackstageのManaged Service「PlaTT」です。
これまで多くの記事を見ていただいてもわかる通り、自社で様々な検証も行っており、皆さんの「面倒」を解消することができると考えています。 ご興味のある方がいらっしゃいましたらぜひ弊社までご連絡ください。
よろしくお願いします。
