TT Lab
はじめる
学ぶ 学習パス コース

CBA — Backstage認定アソシエイト

カタログの整合性診断とゲート

TT Labで続きを見る

目標

引き継いだカタログを静的に診断して、欠陥の4つの種類を見つけ出し、直したコピーを作り、同じ検査をPRで動かすlintゲートとして固めます。Backstageはこの環境にないので、すべての診断は、ファイルを読み取って行います。

なぜ重要なのか

カタログは、登録される瞬間ではなく、時間が経つにつれて腐ります。そして、腐敗の大半を、Backstageはエラーとして知らせてくれません。スキーマに違反したエンティティは表示されますが、存在しない対象を指す参照は、ただ関係が計算されない状態になり、画面に空白として現れます。空の画面は障害のように見えないので、誰も報告せず、そのため誰も直しません。このラボで扱う4つが、実際の現場で繰り返し現れる形です。特に、参照を比べる前に正規化する習慣が重要です。team-ordersとgroup:team-ordersとgroup:default/team-ordersは、同じものを指しているのに、文字列で比べると、問題のない参照が欠陥として報告されます。最後のステップのlintゲートは、きれいな入力で0が出ることだけを確認したのでは、半分です。欠陥をわざと入れたときに、0以外の値が出てはじめて、そのゲートが何かを守っていると言えます。

ステップ

  1. /root/cba-audit/incoming/に、次の8つのファイルを、そのまま作成してください。すべてapiVersion: backstage.io/v1alpha1です。欠けていると書かれているフィールドは、埋めないでください。
    • component-orders.yaml: Component orders-service、spec.type: service、spec.lifecycle: production、spec.owner: group:team-orders、spec.system: commerce-core、spec.providesApisの最初の項目はorders-api、spec.dependsOnの2つの項目はresource:orders-dbとcomponent:ledger-serviceです。
    • component-ledger.yaml: Component ledger-service、spec.type: service、spec.lifecycle: production、spec.owner: group:team-ledger、spec.system: finance-core、spec.dependsOnの最初の項目はcomponent:orders-serviceです。
    • component-report.yaml: Component report-worker、spec.type: service、spec.owner: group:team-analytics、spec.system: commerce-core、spec.dependsOnの最初の項目はresource:analytics-warehouseです。spec.lifecycleはありません。
    • api-orders.yaml: API orders-api、spec.type: openapi、spec.lifecycle: production、spec.system: commerce-coreです。spec.ownerはありません。
    • resource-orders-db.yaml: Resource orders-db、spec.type: database、spec.owner: group:team-storage、spec.system: commerce-coreです。
    • system-commerce-core.yaml: System commerce-core、spec.owner: group:team-orders、spec.domain: retail-opsです。
    • group-team-orders.yaml: Group team-orders、spec.type: teamです。
    • group-team-ledger.yaml: Group team-ledger、spec.type: teamです。
  2. /root/cba-audit/missing-required.txtに、必須フィールドが欠けている箇所を、1行に1つずつ書いてください。形式は<정규화된 엔티티 참조> <필드 경로>(プレースホルダーは、正規化されたエンティティ参照とフィールドパスです)です。必須フィールドは、すべてのkindに共通してapiVersion、kind、metadata.nameで、ここに、ComponentとAPIはspec.type・spec.lifecycle・spec.owner、Resourceはspec.type・spec.owner、SystemとDomainはspec.owner、Groupはspec.typeが加わります。
  3. /root/cba-audit/dangling-owners.txtに、spec.ownerがこのディレクトリにないグループを指している場合を書いてください。形式は<엔티티 참조> <정규화한 소유자 참조>(プレースホルダーは、エンティティ参照と、正規化したオーナー参照です)です。オーナーのデフォルトのkindはgroup、ネームスペースのデフォルト値はdefaultです。
  4. /root/cba-audit/dangling-refs.txtに、オーナーを除いた残りの参照が、存在しない対象を指している場合を書いてください。対象のフィールドは、spec.system(デフォルトのkindはsystem)、spec.domain(domain)、spec.dependsOn(component)、spec.providesApis(api)です。形式は<가리킨 쪽 참조> <없는 대상의 참조>(プレースホルダーは、指した側の参照と、存在しない対象の参照です)です。
  5. /root/cba-audit/dependency-cycle.txtに、spec.dependsOnのエッジをたどったときに、循環に引っかかるエンティティの参照を、1行に1つずつ書いてください。実際に存在するエンティティを指すエッジだけを数えます。
  6. /root/cba-audit/fixed/に、直したカタログを作成してください。ステップ2–5の4つの診断をfixed/に対してもう一度実行したときに、すべて0件である必要があり、incoming/にあった8つのエンティティは、kindと名前がそのままで、すべて残っている必要があります。必要なら、存在しないエンティティを新しく作ってもかまいません。
  7. /root/cba-audit/lint.shを書いてください。最初の引数として受け取ったディレクトリを検査して、必須フィールドの欠落や、存在しない対象を指す参照が1つでもあれば0以外の値で、何もなければ0で終了する必要があります。採点ツールは、このスクリプトを、incoming/、fixed/、そして欠陥を1つずつ仕込んだディレクトリ2つに対して実行します。
  8. 監査の結果を、クラスターに残してください。ネームスペースcba-auditを作成し(ラベルapp.kubernetes.io/part-of: developer-portal)、その中にConfigMap catalog-auditを作成してください。キーは3つです。incoming-findingsはステップ2–5で見つけた欠陥の総件数、fixed-findingsは0、entitiesはfixed/の中のエンティティファイルの個数です。

参考

引き継いだカタログの再現

/root/cba-audit/incoming/に、次の8つのファイルを、そのまま作成してください。すべてapiVersion: backstage.io/v1alpha1です。欠けていると書かれているフィールドは、埋めないでください。

指示文に書かれたとおりに、移してください。欠けていると書かれているフィールドは、埋めてはいけません。その欠陥が、あとのステップで診断する対象です。

必須フィールドの欠落の診断

/root/cba-audit/missing-required.txtに、必須フィールドが欠けている箇所を、1行に1つずつ書いてください。形式は<정규화된 엔티티 참조> <필드 경로>(プレースホルダーは、正規化されたエンティティ参照とフィールドパスです)です。必須フィールドは、すべてのkindに共通してapiVersion、kind、metadata.nameで、ここに、ComponentとAPIはspec.type・spec.lifecycle・spec.owner、Resourceはspec.type・spec.owner、SystemとDomainはspec.owner、Groupはspec.typeが加わります。

必須フィールドは、kindごとに違います。ComponentとAPIはtype、lifecycle、ownerの3つがすべて必要で、Resourceは2つ、SystemとDomainはownerの1つです。

切れたオーナーの診断

/root/cba-audit/dangling-owners.txtに、spec.ownerがこのディレクトリにないグループを指している場合を書いてください。形式は<엔티티 참조> <정규화한 소유자 참조>(プレースホルダーは、エンティティ参照と、正規化したオーナー参照です)です。オーナーのデフォルトのkindはgroup、ネームスペースのデフォルト値はdefaultです。

オーナーの値は、kindを省略できるので、比べる前に正規化する必要があります。ネームスペースのデフォルト値はdefaultです。

切れた参照の診断

/root/cba-audit/dangling-refs.txtに、オーナーを除いた残りの参照が、存在しない対象を指している場合を書いてください。対象のフィールドは、spec.system(デフォルトのkindはsystem)、spec.domain(domain)、spec.dependsOn(component)、spec.providesApis(api)です。形式は<가리킨 쪽 참조> <없는 대상의 참조>(プレースホルダーは、指した側の参照と、存在しない対象の参照です)です。

オーナーのほかにも、対象を指すフィールドが4つあります。フィールドごとにデフォルトのkindが違うので、正規化するときにそれを合わせる必要があります。

依存の循環の診断

/root/cba-audit/dependency-cycle.txtに、spec.dependsOnのエッジをたどったときに、循環に引っかかるエンティティの参照を、1行に1つずつ書いてください。実際に存在するエンティティを指すエッジだけを数えます。

dependsOnだけをたどればよいです。実際に存在するエンティティを指すエッジだけを数え、その上で、自分自身に戻ってくる道があるエンティティを探してください。

直したカタログ

/root/cba-audit/fixed/に、直したカタログを作成してください。ステップ2–5の4つの診断をfixed/に対してもう一度実行したときに、すべて0件である必要があり、incoming/にあった8つのエンティティは、kindと名前がそのままで、すべて残っている必要があります。必要なら、存在しないエンティティを新しく作ってもかまいません。

組織データを先に埋め、そのあとにまとまり、最後に個別のエンティティを直してください。欠陥のあるエンティティを削除して、一覧をきれいにすることは、直したことではありません。

PRで動くlintゲート

/root/cba-audit/lint.shを書いてください。最初の引数として受け取ったディレクトリを検査して、必須フィールドの欠落や、存在しない対象を指す参照が1つでもあれば0以外の値で、何もなければ0で終了する必要があります。採点ツールは、このスクリプトを、incoming/、fixed/、そして欠陥を1つずつ仕込んだディレクトリ2つに対して実行します。

ゲートは、きれいな入力で0を出すだけでは足りません。欠陥をわざと入れてみて、0以外の値が出るかを、必ず確認してください。採点ツールも、そのようにテストします。

監査の結果をクラスターに

監査の結果を、クラスターに残してください。ネームスペースcba-auditを作成し(ラベルapp.kubernetes.io/part-of: developer-portal)、その中にConfigMap catalog-auditを作成してください。キーは3つです。incoming-findingsはステップ2–5で見つけた欠陥の総件数、fixed-findingsは0、entitiesはfixed/の中のエンティティファイルの個数です。

数字を手で数えずに、前のステップの成果物から計算して入れてください。採点ツールは、元のディレクトリから同じ値を再計算して、照らし合わせます。