Belajar Platform Engineer - Internal Developer Portal (Backstage)

#Pendahuluan

Setelah di episode 5 platform kita memiliki fondasi yang bisa di-review dan menyembuhkan dirinya sendiri (IaC + GitOps), muncul pertanyaan pengalaman: bagaimana developer menemukan dan memakai semua ini? Fondasi hebat yang tidak bisa ditemukan developer sama saja tidak ada. Jawabannya adalah Internal Developer Portal (IDP) — dan referensi paling populer untuk itu adalah Backstage, yang diciptakan Spotify dan di-donasikan ke CNCF.

Mengapa portal penting? Ingat mindset produk dari episode 2: platform harus dipakai. Backstage mengubah platform dari "kumpulan dokumen dan tool yang tersebar" menjadi satu antarmuka di mana developer bisa menemukan service, mem-bootstrap service baru, dan melihat status semuanya. Inilah experience layer platform engineering.

#Apa Itu Backstage?

Backstage adalah platform open-source untuk membangun developer portals. Tiga modul intinya membentuk fondasi IDP:

1. Software Catalog — database semua komponen software organisasi (services, libraries, websites) dengan metadata dan ownership.
2. Software Templates (Scaffolder) — mekanisme men-generate service baru dari template golden path (ini yang kita rancang di episode 3).
3. Plugins — ekosistem fitur yang terpasang ke portal (CI/CD status, observability, docs, cost, dll).

#Software Catalog: Source of Truth Komponen

#Konsep entity

Semua hal di Backstage direpresentasikan sebagai entity dalam catalog — service, website, library, dan bahkan environment. Entity didefinisikan dalam file catalog-info.yaml di repository service, sehingga catalog selalu sinkron dengan kode:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  title: Payments API
  description: Service pembayaran utama
  annotations:
    github.com/project-slug: org/payments-api
    argocd/app-name: payments-api
    prometheus.io/scrape: "true"
spec:
  type: service
  lifecycle: production
  owner: group:team-payments
  system: payments-system
  dependsOn:
    - component:payments-db

Perhatikan annotations: di sinilah portal terhubung ke tool lain. Annotation argocd/app-name membuat Backstage menampilkan status ArgoCD; prometheus.io/scrape menghubungkan ke grafana dashboard. Catalog tanpa annotation adalah buku telepon; catalog dengan annotation adalah panel kontrol.

#Owner sebagai Konsep Kunci

Field owner bukan formalitas — ia menentukan siapa yang dianggap bertanggung jawab atas service. Backstage mendukung konsep ownership groups yang biasanya dipetakan ke tim di SSO. Dengan ini, pertanyaan "service ini siapa yang punya?" selalu punya jawaban otomatis.

#Scaffolder: Golden Path Menjadi Nyata

Ini koneksi langsung ke episode 3. Template Backstage mengambil golden path dan mengubahnya menjadi alur kerja di portal:

1. Developer klik "Create new service".
2. Backstage menampilkan form (nama, owner, language).
3. Backstage menjalankan steps: fetch template → publish GitHub repo → register di catalog → trigger CI.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: python-service
  title: Python FastAPI Service
  description: Golden path service FastAPI
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Informasi Service
      properties:
        component_id:
          type: string
        description:
          type: string
        owner:
          type: string
  steps:
    - id: fetch-template
      action: fetch:template
      input:
        url: ./skeletons/fastapi
        values:
          name: ${{ parameters.component_id }}
    - id: publish
      action: publish:github
      input:
        repoUrl: ${{ parameters.repoUrl }}
        defaultBranch: main
    - id: register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}

Setelah template ini dipublish, alur "onboarding service baru" yang tadinya melibatkan 3 sistem dan 2 hari menjadi satu klik + 3 menit. Template adalah golden path yang paling terlihat oleh developer.

#Setup Backstage

#Instalasi Dasar

Setup Backstage modern menggunakan npx @backstage/create-app. Persiapkan di lab kalian:

npx @backstage/create-app@latest --skip-install
cd backstage
yarn install
yarn dev

Setelah yarn dev, portal berjalan di localhost:3000. Dari sini kalian bisa:

1. Tambah catalog locations — arahkan Backstage ke repo kalian (contoh: ./catalog-info.yaml).
2. Daftarkan template — taruh template scaffolding di folder templates/ dan daftarkan.
3. Pasang plugin — misalnya plugin ArgoCD dan Grafana (instalasi via yarn add lalu konfigurasi di app-config.yaml).

#Konfigurasi Dasar

File app-config.yaml adalah pusat konfigurasi portal:

app:
  title: Platform Portal
  baseUrl: http://localhost:3000
 
backend:
  baseUrl: http://localhost:3000
  listen:
    port: 3000
  database:
    client: postgres
    connection:
      host: ${POSTGRES_HOST}
      port: 5432
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
 
auth:
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

#Plugin Ecosystem

Kekuatan Backstage justru di ekosistem plugin. Daripada membangun fitur sendiri, pasang plugin yang sudah ada dan fokuskan energi pada konfigurasi + integrasi. Plugin yang paling sering dipakai di platform production:

Perhatikan polanya: semua plugin ini adalah permukaan depan dari yang sudah kita bangun. IDP tidak menambah tooling baru — ia menyatukan yang sudah ada. Ini prinsip penting: jangan pasang portal dulu lalu membangun tooling di belakangnya; bangun tooling (seperti kita di episode 4-5) lalu rekatkan dengan portal.

#Common Pitfalls

1. Portal tanpa katalog terisi — Backstage kosong tidak memberi nilai; isi catalog dulu dari repo yang paling penting.
2. Semua lewat portal, tidak ada yang otomatis — portal yang hanya memindahkan tiket dari Jira ke Backstage bukan improvement.
3. Too many plugins — portal penuh widget yang tidak terpakai; mulailah dengan 3-5 plugin yang benar-benar dipakai.
4. Abandoning default — Backstage kustomisasi berat sejak awal membuat upgrade menyakitkan; kurangi fork, perbanyak konfigurasi.

#Penutup

Inti yang harus dibawa pulang:

• Backstage = Software Catalog + Scaffolder + Plugins.
• Catalog-info.yaml dengan annotations menghubungkan portal ke tooling yang ada.
• Template scaffolder mengubah golden path menjadi alur satu klik.
• Mulai dengan catalog terisi dan sedikit plugin, bukan portal hiasan.

Di episode 7 selanjutnya kita akan melengkapi pengalaman developer di sisi build dan release: CI/CD platform — standardisasi pipeline, artifact registry, dan template CI yang membuat seluruh proses dari push ke production konsisten dan aman!