Belajar Backstage - Software Catalog Dasar

#Pendahuluan

Di episode 3, kalian berhasil menjalankan Backstage pertama dengan yarn dev. Sekarang saatnya menyelami primitif yang paling sentral: Software Catalog. Episode 4 ini membahas dasar-dasarnya — apa itu entity, delapan kind yang dikenal Backstage, bagaimana file catalog-info.yaml mendeskripsikan sebuah entitas, dan bagaimana hubungan antar entity terbentuk.

Software Catalog adalah salah satu halaman yang paling sering kalian buka saat memakai Backstage. Ia bukan sekadar daftar — ia grafik pengetahuan yang merepresentasikan seluruh software organization. Setiap entri bisa diklik untuk melihat detail, pemilik, dependensi, dan dokumentasinya. Memahami model data di baliknya adalah bekal untuk semua episode berikutnya, karena scaffolder, TechDocs, dan search semuanya bekerja di atas katalog.

#Konsep Entity

#Apa itu Entity

Dalam Software Catalog, segala sesuatu direpresentasikan sebagai entity. Sebuah service, website, API, tim, hingga domain bisnis bisa menjadi entity. Setiap entity dideskripsikan oleh file YAML dan dibaca oleh catalog untuk dijadikan entri yang bisa dicari, dijelajahi, dan direlasikan. Entity inilah yang menjawab masalah discoverability yang kalian pelajari di episode 1.

#Entity Kind

Setiap entity punya kind — jenis yang menentukan makna dan kolom yang tersedia. Backstage mengenal delapan kind inti:

Component adalah kind yang paling sering dipakai — setiap service di repositori kalian biasanya dideskripsikan sebagai Component. Kind lainnya berfungsi mengelompokkan dan menghubungkan entity.

#catalog-info.yaml

Cara mendeskripsikan entity adalah lewat file catalog-info.yaml yang disimpan di dalam repositori masing-masing. Contohnya:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: Layanan pemrosesan pesanan
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  owner: team-checkout
  system: e-commerce
  providesApis:
    - order-api

File ini punya tiga blok besar: apiVersion, metadata, dan spec.

#Metadata

Blok metadata berisi informasi umum entity: name sebagai identitas unik, description untuk penjelasan, dan annotations. Anotasi adalah ruang untuk metadata tambahan yang bisa dibaca plugin. Beberapa anotasi memakai namespace khusus backstage.io/* — misalnya backstage.io/techdocs-ref yang menunjuk ke lokasi dokumentasi TechDocs entity tersebut. Anotasi semacam ini menjadi semacam kontrak antara entity dan plugin yang memakainya.

#Spec

Blok spec berisi detail yang spesifik per kind. Untuk Component, kolom type menentukan apakah entity adalah service, website, atau library; kolom owner menunjuk siapa yang bertanggung jawab; kolom system mengelompokkan component ke dalam sistem; dan providesApis mendaftar API yang disediakan. Isi spec sangat bergantung pada kind — kind yang berbeda punya kolom spec yang berbeda.

#Relasi Antar Entity

Entity tidak berdiri sendiri — mereka saling terhubung lewat relations. Tiga relasi yang paling umum adalah:

Relasi ini biasanya tidak ditulis eksplisit sebagai daftar, melainkan disimpulkan dari isi spec. Ketika kalian menulis owner: team-checkout, catalog membacanya menjadi relasi ownedBy ke Group team-checkout. Ketika kalian menulis system: e-commerce, terbentuk relasi partOf ke System tersebut. Dengan cara ini, grafik hubungan seluruh service bisa digambar secara otomatis — dan kalian bisa melihat siapa memiliki apa hanya dengan menjelajahi catalog.

#Menghubungkan Entity dalam Satu Grafik

Agar relasi terbentuk, entity yang dirujuk juga harus ada di catalog. Perhatikan System dan Group yang menjadi tujuan rujukan pada catalog-info.yaml di atas:

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: e-commerce
spec:
  owner: group:commerce-platform
---
apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: team-checkout
spec:
  type: team
  children: []

Tanda --- pada contoh di atas memisahkan dua entity dalam satu file — Backstage memperbolehkan lebih dari satu entity per file. Dengan adanya System e-commerce dan Group team-checkout, semua relasi yang dirujuk Component order-service bisa tersambung: partOf menuju System, ownedBy menuju Group, dan providesApi menuju API yang didaftarkan.

#Penutup

Pada episode 4 ini, kalian memahami dasar Software Catalog: konsep entity, delapan kind yang dikenal Backstage, struktur catalog-info.yaml dengan metadata dan spec, anotasi backstage.io/*, serta relasi antar entity seperti ownedBy, partOf, dan providesApi.

Inti yang harus dibawa pulang:

• Entity adalah unit dasar catalog — service, tim, dan API semuanya adalah entity.
• Kind menentukan bentuk entity — delapan kind inti mencakup hampir semua kebutuhan.
• catalog-info.yaml adalah sumber deskripsi — disimpan di dalam repositori masing-masing.
• Relasi disimpulkan dari spec — owner, system, dan providesApi membentuk jaringan otomatis.

Di episode 5 berikutnya, kita membahas bagaimana catalog mendapatkan semua entity tersebut: catalog ingestion dan processing — dari static locations, URL dan file locations, hingga entity providers, beserta pipeline pengolahan dari provider sampai entity siap dipakai.