ソフトウェアカタログのエンティティ作成

目標

Backstageソフトウェアカタログのエンティティ8つの種類を自分で書き、その間の関係の宣言と参照の形式を、手に慣らします。最後に、同じ所有権の情報を実際のクラスターのワークロードに表現して、2つの世界をつなぎます。

なぜ重要なのか

カタログは一覧ではなく、関係のグラフです。spec.owner、spec.system、spec.providesApisを片側だけに宣言すると、カタログが双方向の関係を計算してくれます。そのため、どのフィールドをどこに書くかが、そのままグラフの形を決めます。特にオーナーは、カタログでたった1つだけ正確でなければならないとしたら、それだと言えるほど重要です。障害時のページ、脆弱性のチケット、コストの帰属、廃止の判断が、すべてオーナーで分かれるからです。そして、オーナーは必ず人ではなくチームでなければなりません。人は退職し、チームは引き継がれるからです。このラボで作ったファイルは、実際の運用では、サービスのコードリポジトリのルートに一緒にコミットされ、ディスカバリーで自動登録されます。Backstage自体はこの環境にないので、採点は、ファイルとクラスターのオブジェクトを読み取って行います。

ステップ

/root/cba-catalog/catalog-info.yamlにComponentを書いてください。apiVersion: backstage.io/v1alpha1、kind: Component、metadata.name: checkout-service、metadata.descriptionは任意の文、metadata.annotationsにbackstage.io/techdocs-ref: dir:.とbackstage.io/kubernetes-id: checkout-service、spec.type: service、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce、spec.providesApisの最初の項目はcheckout-apiです。
/root/cba-catalog/api-checkout.yamlにAPIを書いてください。kind: API、metadata.name: checkout-api、spec.type: openapi、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce、spec.definitionには、openapi: 3.0.0で始まる複数行の文字列(ブロックスカラー)を入れます。
/root/cba-catalog/resource-db.yamlにResourceを書いてください。kind: Resource、metadata.name: checkout-db、spec.type: database、spec.owner: group:team-checkout、spec.system: commerceです。
/root/cba-catalog/system-commerce.yamlにSystemを書いてください。kind: System、metadata.name: commerce、spec.owner: group:team-checkout、spec.domain: retailです。/root/cba-catalog/domain-retail.yamlにDomainを書いてください。kind: Domain、metadata.name: retail、spec.owner: group:team-checkoutです。
/root/cba-catalog/group-team-checkout.yamlにGroupを書いてください。kind: Group、metadata.name: team-checkout、spec.type: team、spec.profile.displayNameは任意の値、spec.children: []です。/root/cba-catalog/user-youngju.yamlにUserを書いてください。kind: User、metadata.name: youngju、spec.memberOfの最初の項目はteam-checkoutです。
/root/cba-catalog/all.yamlにLocationを書いてください。kind: Location、metadata.name: cba-catalog-all、spec.type: url、spec.targetsには、前に作ったエンティティファイル7つを、./catalog-info.yamlのように相対パスで並べます(合計7つ)。
同じ所有権の情報を、クラスターに表現してください。ネームスペースcba-commerceを作成し(ラベルapp.kubernetes.io/part-of: commerce)、その中にDeployment checkout-serviceを作成してください。メタデータのラベルにbackstage.io/kubernetes-id: checkout-service、app.kubernetes.io/name: checkout-service、app.kubernetes.io/part-of: commerceを入れ、さらにPodテンプレートのラベルにもbackstage.io/kubernetes-id: checkout-serviceを入れてください。イメージはnginx:1.27-alpine、replicasは1です。
/root/cba-catalog/refs.txtに、前に作ったすべてのエンティティ(Component、API、Resource、System、Domain、Group、User。7つ)の正規化された参照を、1行に1つずつ書いてください。形式は<소문자 kind>:default/<이름>(プレースホルダーは小文字のkindと名前です)です。例: component:default/checkout-service。Locationは除外します。

参考

エンティティ参照の形式は[<kind>:][<namespace>/]<name>で、ネームスペースのデフォルト値はdefaultです。
複数行の文字列は、YAMLのブロックスカラー(|)で入れます。
よくある間違い1: spec.ownerを人の名前で書くこと。人は去り、チームは残ります。
よくある間違い2: providesApisを、API側にも反対向きに書こうとすることです。関係は、片側の宣言で、カタログが双方向に計算します。
よくある間違い3: backstage.io/kubernetes-idを、エンティティにはラベルとして、ワークロードにはアノテーションとして入れること。方向が逆です。エンティティにはアノテーション、ワークロードにはラベルです。

Componentエンティティ

/root/cba-catalog/catalog-info.yamlにComponentを書いてください。apiVersion: backstage.io/v1alpha1、kind: Component、metadata.name: checkout-service、metadata.descriptionは任意の文、metadata.annotationsにbackstage.io/techdocs-ref: dir:.とbackstage.io/kubernetes-id: checkout-service、spec.type: service、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce、spec.providesApisの最初の項目はcheckout-apiです。

Componentの必須のspecは、type、lifecycle、ownerです。オーナーは、人ではなくチームを指すように書き、参照形式の前の部分を明示してください。

APIエンティティ

/root/cba-catalog/api-checkout.yamlにAPIを書いてください。kind: API、metadata.name: checkout-api、spec.type: openapi、spec.lifecycle: production、spec.owner: group:team-checkout、spec.system: commerce、spec.definitionには、openapi: 3.0.0で始まる複数行の文字列(ブロックスカラー)を入れます。

APIエンティティは、定義(definition)を文字列として持ちます。YAMLのブロックスカラーを使えば、複数行をそのまま入れられます。

Resourceエンティティ

/root/cba-catalog/resource-db.yamlにResourceを書いてください。kind: Resource、metadata.name: checkout-db、spec.type: database、spec.owner: group:team-checkout、spec.system: commerceです。

Resourceは、コンポーネントが必要とするインフラです。種類を表すフィールド名は、Componentと同じです。

SystemとDomain

/root/cba-catalog/system-commerce.yamlにSystemを書いてください。kind: System、metadata.name: commerce、spec.owner: group:team-checkout、spec.domain: retailです。/root/cba-catalog/domain-retail.yamlにDomainを書いてください。kind: Domain、metadata.name: retail、spec.owner: group:team-checkoutです。

Systemは一緒に動作するもののまとまりで、Domainはシステムの上位の領域です。2つをつなぐフィールドは、System側にあります。

GroupとUser

/root/cba-catalog/group-team-checkout.yamlにGroupを書いてください。kind: Group、metadata.name: team-checkout、spec.type: team、spec.profile.displayNameは任意の値、spec.children: []です。/root/cba-catalog/user-youngju.yamlにUserを書いてください。kind: User、metadata.name: youngju、spec.memberOfの最初の項目はteam-checkoutです。

Groupはチーム、Userは人です。人がどのチームに属するかを表すフィールドは、User側にあります。

Locationでまとめる

/root/cba-catalog/all.yamlにLocationを書いてください。kind: Location、metadata.name: cba-catalog-all、spec.type: url、spec.targetsには、前に作ったエンティティファイル7つを、./catalog-info.yamlのように相対パスで並べます(合計7つ)。

Locationは、ほかのエンティティファイルを指す道しるべです。指す対象が実際に存在してはじめて意味があります。

同じ所有権をクラスターのラベルで表現する

同じ所有権の情報を、クラスターに表現してください。ネームスペースcba-commerceを作成し(ラベルapp.kubernetes.io/part-of: commerce)、その中にDeployment checkout-serviceを作成してください。メタデータのラベルにbackstage.io/kubernetes-id: checkout-service、app.kubernetes.io/name: checkout-service、app.kubernetes.io/part-of: commerceを入れ、さらにPodテンプレートのラベルにもbackstage.io/kubernetes-id: checkout-serviceを入れてください。イメージはnginx:1.27-alpine、replicasは1です。

Kubernetesプラグインは、エンティティのアノテーションの値と同じ値を持つ、ワークロードのラベルを探します。アノテーションとラベルのうち、どちらがエンティティで、どちらがワークロードかを区別してください。

エンティティ参照の正規化

/root/cba-catalog/refs.txtに、前に作ったすべてのエンティティ(Component、API、Resource、System、Domain、Group、User。7つ)の正規化された参照を、1行に1つずつ書いてください。形式は<소문자 kind>:default/<이름>(プレースホルダーは小文字のkindと名前です)です。例: component:default/checkout-service。Locationは除外します。

正規化された形式は、kindを小文字にし、ネームスペースを省略せずに書きます。前に作ったすべてのエンティティが対象です。