Belajar Backstage - Catalog Advanced & Data Model

#Pendahuluan

Di episode 5, kalian mempelajari ingestion dan processing: file catalog-info.yaml berubah menjadi entity. Di episode 10, kalian membuat entity lewat scaffolder. Episode 11 menyatukan keduanya dari sisi data: Catalog Advanced & Data Model. Sejauh ini entity terlihat seperti kartu berdiri sendiri — episode ini memperlihatkan bahwa kartu-kartu itu sebenarnya terhubung. Ownership, partOf, dependsOn, dan providesApi membentuk jaring yang menjelaskan siapa memiliki apa, komponen bergantung pada apa, dan sistem mana yang menaungi semuanya. Di akhir episode, kalian juga akan menjaga jaring itu tetap sehat.

#Konsep Entity Relations

#Relasi Menghubungkan Entity

Sebuah entity hampir tidak pernah berdiri sendiri. Backstage memodelkan hubungan antar entity lewat relations, yang dideklarasikan di bagian spec dari catalog-info.yaml. Relasi yang paling mendasar untuk dipahami:

#Relasi dalam Satu File

Semua relasi di atas bisa dinyatakan dalam satu catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api
  description: API pembayaran internal
spec:
  type: service
  owner: group:platform-team
  system: payments-system
  dependsOn:
    - resource:payment-database
    - component:notification-service
  providesApis:
    - payment-api

Bacaan blok di atas: payment-api dimiliki group:platform-team, menjadi bagian dari payments-system, bergantung pada payment-database dan notification-service, serta menyediakan API payment-api. Catalog menerjemahkan setiap baris ini menjadi relation dua arah — dari payment-api terlihat apa yang ia miliki, dan dari payment-database terlihat siapa yang bergantung padanya.

#Pemodelan System, Domain, dan Resource

#Empat Kind yang Bekerja Bersama

Entity relations akan terasa sia-sia tanpa kind yang menaunginya. Empat kind berikut adalah tulang punggung pemodelan:

• Domain — area bisnis terbesar, misalnya pembayaran atau logistik.
• System — kumpulan komponen yang bekerja sama memenuhi satu tujuan, naungan dari banyak partOf.
• Resource — ketergantungan non-software seperti database, cluster, atau bucket.
• Component — unit software sungguhan: service, library, website.

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: payments-system
  description: Sistem pembayaran terpadu
spec:
  owner: group:platform-team
  domain: fintech-domain

System mendefinisikan owner dan domain yang menaunginya, sementara komponen menautkan dirinya lewat system: payments-system. Hasilnya, katalog bisa menjawab pertanyaan berjenjang: domain mana yang menaungi sistem ini, sistem apa saja di dalamnya, dan resource apa yang dipakai semua komponennya.

#Resource Sebagai Ketergantungan

Resource menangkap fakta bahwa komponen bergantung pada sesuatu yang bukan komponen. Database terkelola, Kafka cluster, atau bucket S3 masing-masing direpresentasikan sebagai entity Resource dengan spec.type seperti database, message-queue, atau object-store. Komponen yang memakainya menulis dependsOn ke resource itu — dan dari situ katalog menggambar grafik ketergantungan yang terlihat.

#Catalog Filters

#Menyaring Entity di API dan UI

Katalog besar bisa berisi ribuan entity. Catalog filters mempersempit tampilan berdasarkan kind, type, tag, atau pemilik. Di UI, filter dipilih dari dropdown; di API, filter dikirim sebagai parameter query — beberapa nilai filter di-OR-kan, sedangkan nilai dalam satu filter di-AND-kan.

curl "http://localhost:7007/api/catalog/entities?filter=kind=component,metadata.tags=backend"

Query di atas mengambil entity dengan kind=component dan tag backend. Format filter sangat berguna untuk mengotomatisasi penemuan entity — misalnya mengambil semua service milik satu grup untuk dashboard atau untuk laporan kepemilikan.

#Validasi Entity dan catalog-validator di CI

#Memvalidasi Sebelum Masuk

Kualitas katalog dimulai dari file sumber. Paket @backstage/catalog-model menyediakan validateEntity untuk memeriksa bahwa sebuah entity memenuhi aturan: field wajib ada, tipe data benar, dan struktur valid. Menjalankan validasi ini di CI berarti pull request yang membawa catalog-info.yaml rusak akan ditolak sebelum menyentuh katalog.

import { validateEntity } from '@backstage/catalog-model/validation';
import { parseEntityYaml } from '@backstage/catalog-model';
 
export async function validateCatalogFile(filePath: string) {
  const entity = parseEntityYaml(filePath);
  await validateEntity(entity);
}

validateEntity melempar error saat entity tidak valid, sehingga skrip CI bisa langsung menggagalkan build. Ini sederhana tetapi efektif: seluruh tim menerima umpan balik yang sama dalam hitungan detik, bukan setelah entity masuk katalog.

#catalog-validator sebagai Langkah CI

Tambahkan validasi ini sebagai langkah di pipeline — inilah yang dimaksud catalog-validator di CI. Skrip membaca semua file katalog yang berubah di pull request, memvalidasinya, dan hanya melanjutkan jika semuanya lolos. Semakin banyak file catalog-info.yaml yang dideklarasikan secara manual, semakin penting langkah ini.

yarn validate:catalog

Perintah validate:catalog adalah skrip yang memanggil validateEntity untuk setiap file catalog-info.yaml di repository. Dengan langkah ini di CI, kesalahan struktur terdeteksi di titik paling awal dan paling murah untuk diperbaiki.

#Unprocessed Entities

#Antrean Menunggu Processor

Saat lokasi baru didaftarkan, entity yang ditemukan belum langsung siap. Ia adalah unprocessed entity — masuk antrean dan menunggu processor katalog (seperti GitHub, URL, atau file processor) mengolahnya menjadi entity lengkap. Proses ini berjalan berkala, dan hasilnya memicu refresh hingga entity siap ditampilkan.

Unprocessed entities muncul dalam katalog dengan status yang menandakan belum diproses. Jika sebuah entity lama menunggu dalam status ini, kemungkinan besar source-nya tidak bisa dijangkau atau processor gagal — dan di situlah debugging dimulai: cek apakah URL target bisa diakses, apakah token akses masih valid, dan apakah format file sesuai.

#Stale Entity Removal

#Membersihkan yang Tidak Lagi Ada

Sumber entity bisa hilang: repository dihapus, file catalog-info.yaml dihapus, atau lokasi dicabut. Entity yang sumbernya tidak lagi ada disebut stale entity. Katalog menjalankan pembersihan berkala untuk mendeteksi entity semacam ini dan menghapusnya, sehingga katalog tidak menampilkan kartu untuk sesuatu yang sudah tidak hidup.

Proses ini membandingkan entity yang terdaftar dengan sumbernya. Bila sumber sudah tidak ada, entity ditandai dan akhirnya dihapus. Otomasi ini penting: katalog yang bersih adalah katalog yang bisa dipercaya — karena setiap kartu yang tampil mewakili sesuatu yang benar-benar berjalan di organisasi kalian.

#Penutup

Pada episode 11 ini, kalian memahami data model katalog secara utuh: relasi ownership, partOf, dependsOn, dan providesApi, pemodelan System, Domain, dan Resource bersama komponen, filter katalog di API dan UI, validasi entity memakai validateEntity dan catalog-validator di CI, pemahaman terhadap unprocessed entities, serta penghapusan entity stale secara berkala.

Inti yang harus dibawa pulang:

• Relasi adalah jaring, bukan label — ownership, partOf, dependsOn, dan providesApi menghubungkan entity dan menghasilkan grafik yang bisa dijelajahi.
• Domain dan system menaungi komponen — pemodelan berjenjang membuat katalog menjawab pertanyaan dari bisnis hingga resource.
• Kualitas dimulai di CI — validateEntity di pipeline mencegah catalog-info.yaml rusak masuk katalog.
• Katalog butuh perawatan — unprocessed entities menandakan sumber bermasalah, dan entity stale harus dibersihkan berkala.

Di episode 12 berikutnya, kita menyingkap lapisan yang selama ini menyimpan semua data katalog dan pipeline: Persistence & Databases — bagaimana Backstage menyimpan datanya di SQLite untuk pengembangan dan PostgreSQL untuk produksi, peran Knex dan migrasi, hingga cache Redis dan search index untuk skala besar.