ソフトウェアテンプレートとTechDocsの作成

目標

Backstageソフトウェアテンプレートの3つの層(parameters、steps、output)を自分で書き、TechDocs用のmkdocsの設定と、スケルトンのエンティティを作ります。最後に、そのテンプレートが作り出すワークロードを実際のクラスターに作成して、結果を確認します。

なぜ重要なのか

スキャフォルダーの価値は、タイピングを減らすことではなく、検証された経路をデフォルトにすることです。プラットフォームチームが一度踏んだ落とし穴(特定のCRDバージョンが必要だとか、特定の回避経路を使う必要があるとか)を、スケルトンとドキュメントとして固めておけば、ほかの人は二度と踏みません。そして、構造そのものが重要です。parametersがJSON Schemaなので、間違った入力がフォームの段階で止まり、stepsが再利用可能なアクションの組み合わせなので、新しいテンプレートを作るときに、リポジトリの作成とカタログの登録の部分を、書き直さなくて済みます。もう1つ見落としやすい点があります。publish:githubを実行するのは、ユーザーのブラウザーではなく、Backstageバックエンドです。トークンがサーバーにだけあるので、ポータルを通じたセルフサービスのほうが、すべての開発者にトークンを配るよりも安全です。Backstageはこの環境にないので、テンプレートはファイルとして書き、採点はファイルを読み取って行い、最後のステップだけ実際のクラスターを使います。

ステップ

/root/cba-template/template.yamlを書いてください。apiVersion: scaffolder.backstage.io/v1beta3、kind: Template、metadata.name: node-service、metadata.titleは任意の値、metadata.tagsの最初の項目はnodejs、spec.owner: group:team-platform、spec.type: serviceです。
同じファイルにspec.parametersを追加してください。配列の最初の項目に、title(任意の値)、requiredは[name, owner]、properties.nameはtype: stringにpattern: '^[a-z0-9-]+$'とtitle、properties.ownerはtype: stringにtitleを入れます。
同じファイルにspec.stepsを追加してください。ちょうど3つで、順番にid: fetch(action fetch:template、input.url: ./skeleton、input.values.nameにnameパラメーターの置換式)、id: publish(action publish:github)、id: register(action catalog:register、input.repoContentsUrlにpublishステップの出力の参照、input.catalogInfoPath: /catalog-info.yaml)です。
同じファイルにspec.outputを追加してください。linksの最初の項目のtitleはRepository、urlはpublishステップのremoteUrlの出力の参照、entityRefはregisterステップのentityRefの出力の参照です。
/root/cba-template/mkdocs.ymlを書いてください。site_nameは任意の値、navの最初の項目はHome: index.md、pluginsの最初の項目はtechdocs-coreです。そして、/root/cba-template/docs/index.mdに、#で始まる見出しを1行と、説明の段落を書いてください。
/root/cba-template/skeleton/catalog-info.yamlを書いてください。kind: Component、metadata.nameはテンプレートの値の置換式(文字列の中にvalues.nameが入っている必要があります)、metadata.annotationsにbackstage.io/techdocs-ref: dir:.とbackstage.io/kubernetes-id: node-service、spec.type: service、spec.lifecycle: experimental、spec.ownerはownerの値の置換式です。
テンプレートが作り出す結果を、クラスターに作成してください。ネームスペースcba-scaffoldを作成し、その中に、Deployment node-service(ラベルbackstage.io/kubernetes-id: node-serviceとapp.kubernetes.io/part-of: cba-platform、イメージnode:22-alpine、replicas 2、Podテンプレートのラベルにも同じbackstage.io/kubernetes-id)、Service node-service(port 80、targetPort 3000)、そしてConfigMap node-service-techdocs(キーtechdocs-refの値が、ステップ6のスケルトンのアノテーションの値とまったく同じである必要があります)を作成してください。

参考

置換式は、二重の波括弧の前にドル記号が付く形です。フォームの入力はparameters.<이름>(プレースホルダーは名前です)、前のステップの結果はsteps.<id>.output.<필드>(プレースホルダーはステップのidとフィールドです)で参照します。
置換式は、ダブルクォートで囲んでおいてください。YAMLパーサーが波括弧をフローマッピングと誤解する余地をなくします。
publish:githubの出力にはremoteUrlとrepoContentsUrlが、catalog:registerの出力にはentityRefがあります。
よくある間違い1: TemplateのapiVersionをbackstage.io/v1alpha1と書くこと。スキャフォルダーはscaffolder.backstage.io/v1beta3です。
よくある間違い2: parametersを1つのオブジェクトとして書くこと。複数のページに対応するために、配列です。
よくある間違い3: スケルトンのmetadata.nameに固定の文字列を書くこと。テンプレートが作り出すファイルなので、置換式でなければなりません。

Templateマニフェストの骨組み

/root/cba-template/template.yamlを書いてください。apiVersion: scaffolder.backstage.io/v1beta3、kind: Template、metadata.name: node-service、metadata.titleは任意の値、metadata.tagsの最初の項目はnodejs、spec.owner: group:team-platform、spec.type: serviceです。

Templateは、カタログのエンティティとapiVersionが違います。スキャフォルダー専用のグループを使い、オーナーは、ほかのエンティティと同じ参照形式です。

parameters: ユーザーのフォーム

同じファイルにspec.parametersを追加してください。配列の最初の項目に、title(任意の値)、requiredは[name, owner]、properties.nameはtype: stringにpattern: '^[a-z0-9-]+$'とtitle、properties.ownerはtype: stringにtitleを入れます。

parametersはページの配列で、各ページがJSON Schemaです。必須項目のリストと、プロパティの定義がどこに入るかを確認してください。

steps: アクションの組み合わせ

同じファイルにspec.stepsを追加してください。ちょうど3つで、順番にid: fetch(action fetch:template、input.url: ./skeleton、input.values.nameにnameパラメーターの置換式)、id: publish(action publish:github)、id: register(action catalog:register、input.repoContentsUrlにpublishステップの出力の参照、input.catalogInfoPath: /catalog-info.yaml)です。

各ステップは、id、name、action、inputを持ちます。骨組みの取得、リポジトリの作成、カタログの登録が、それぞれどのアクション名だったかを思い出してみてください。

output: 終わったあとに見せるもの

同じファイルにspec.outputを追加してください。linksの最初の項目のtitleはRepository、urlはpublishステップのremoteUrlの出力の参照、entityRefはregisterステップのentityRefの出力の参照です。

前のステップの結果は、ステップのidを通じて参照します。リポジトリのアドレスと、登録されたエンティティの参照が、それぞれどのステップの出力かを考えてください。

mkdocsの設定とドキュメント

/root/cba-template/mkdocs.ymlを書いてください。site_nameは任意の値、navの最初の項目はHome: index.md、pluginsの最初の項目はtechdocs-coreです。そして、/root/cba-template/docs/index.mdに、#で始まる見出しを1行と、説明の段落を書いてください。

TechDocsは、mkdocsを使います。設定ファイルには、サイト名と目次、そしてTechDocs用のプラグインが必要です。

スケルトンのcatalog-info.yaml

/root/cba-template/skeleton/catalog-info.yamlを書いてください。kind: Component、metadata.nameはテンプレートの値の置換式(文字列の中にvalues.nameが入っている必要があります)、metadata.annotationsにbackstage.io/techdocs-ref: dir:.とbackstage.io/kubernetes-id: node-service、spec.type: service、spec.lifecycle: experimental、spec.ownerはownerの値の置換式です。

テンプレートが作り出すファイルなので、名前の位置には、値ではなく置換式が入ります。ドキュメントの場所を指すアノテーションも、忘れないでください。

生成結果をクラスターに適用する

テンプレートが作り出す結果を、クラスターに作成してください。ネームスペースcba-scaffoldを作成し、その中に、Deployment node-service(ラベルbackstage.io/kubernetes-id: node-serviceとapp.kubernetes.io/part-of: cba-platform、イメージnode:22-alpine、replicas 2、Podテンプレートのラベルにも同じbackstage.io/kubernetes-id)、Service node-service(port 80、targetPort 3000)、そしてConfigMap node-service-techdocs(キーtechdocs-refの値が、ステップ6のスケルトンのアノテーションの値とまったく同じである必要があります)を作成してください。

テンプレートが作り出すワークロードを、自分で作成してみます。スケルトンに書いたドキュメントの参照値と、クラスターに入れる値が同じである必要があります。