Backstage ile Internal Developer Portal: Kurulum ve En İyi Uygulamalar

Modern yazılım geliştirme ekiplerinin karşılaştığı en büyük zorluklardan biri, binlerce mikroservis arasında kaybolmak ve ihtiyaç duydukları bilgilere, dokümantasyona veya altyapı araçlarına hızlıca erişememektir. Spotify tarafından açık kaynak olarak geliştirilen Backstage, bu problemi çözmek için tasarlanmış güçlü bir Internal Developer Portal çözümüdür. Bu makalede Backstage'in ne olduğunu, nasıl çalıştığını, kurulum sürecini ve kurumsal ortamda nasıl kullanılabileceğini detaylı olarak inceleyeceğiz.

Backstage Nedir ve Neden Kullanılmalıdır

Backstage, Spotify tarafından 2020 yılında açık kaynak olarak sunulan ve günümüzde CNCF (Cloud Native Computing Foundation) altında geliştirilen bir platform mühendisliği aracıdır. Temel amacı, geliştiricilerin ihtiyaç duyduğu tüm araçları, dokümantasyonu ve süreçleri tek bir noktadan erişilebilir kılmaktır. Geleneksel yaklaşımda her ekip kendi dokümantasyonunu, CI/CD pipeline'larını ve altyapı araçlarını bağımsız olarak yönetirken, Backstage bu chaos'ı merkezi bir portal aracılığıyla düzene sokar.

Platform Mühendisliği ve Internal Developer Portal Kavramları

Platform mühendisliği, son yıllarda DevOps evriminde öne çıkan bir disiplindir. Amaç, geliştirici ekiplerine self-servis araçlar ve otomasyonlar sunarak üretkenliklerini artırmaktır. Internal Developer Portal (IDP) ise bu platformun kullanıcı arayüzüdür. Backstage, bir IDP framework'ü olarak işlev görür; ancak tek başına bir altyapı sağlayıcı değildir. Backstage'in gücü, üzerine inşa edilen eklentiler ve entegrasyonlarla ortaya çıkar.

Backstage'in Temel Bileşenleri

Backstage dört ana bileşenden oluşur. İlk olarak Software Catalog, organizasyonunuzdaki tüm yazılım varlıklarını (servisler, API'ler, kütüphaneler, veritabanları) merkezi olarak depolar ve yönetir. İkinci bileşen olan TechDocs, kod içi dokümantasyon oluşturma ve yayınlama altyapısı sağlar. Scaffolder, standart şablonlar kullanarak yeni projeler oluşturmanızı otomatikleştirir. Son olarak Kubernetes plugin, Kubernetes kaynaklarını doğrudan Backstage arayüzünden görüntüleme ve yönetme imkanı sunar.

Software Catalog: Backstage'in Kalbi

Software Catalog, Backstage'in en kritik ve güçlü özelliğidir. Tüm organizasyonun yazılım varlıklarını keşfedilebilir, izlenebilir ve yönetilebilir hale getirir. Catalog olmadan Backstage, sadece boş bir kabuktan ibarettir; diğer tüm özellikler (TechDocs, Scaffolder, Kubernetes plugin) catalog entity'leri üzerine inşa edilir.

Entity Türleri ve Veri Modeli

Backstage, altı temel entity türü destekler. Component, koddan oluşan yazılım birimlerini temsil eder; backend servisi, web uygulaması veya kütüphane olabilir. API, bir component'in sağladığı veya kullandığı arayüzleri tanımlar; OpenAPI, gRPC, GraphQL veya AsyncAPI formatlarında olabilir. Resource, bir component'in bağımlı olduğu altyapı kaynaklarını ifade eder; veritabanı, S3 bucket veya mesaj kuyruğu gibi. System, birbirleriyle ilişkili component'lerin oluşturduğu mantıksal grubu temsil eder. Domain, daha üst seviye sistem gruplandırması sağlar. Son olarak Group ve User, organizasyon yapısını ve ownership modelini tanımlar.

Catalog-Info.yaml Dosyası ile Entity Tanımlama

Her entity, repository'nizin kök dizininde veya belirli bir klasörde bulunan catalog-info.yaml dosyası ile tanımlanır. Bu dosya formatı, Kubernetes manifest'lerinden ilham alınarak tasarlanmıştır ve YAML formatında yazılır.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: odeme-api
  description: Ödeme işlemleri API servisi
  annotations:
    github.com/project-slug: sirket/odeme-api
    backstage.io/techdocs-ref: dir:.
    backstage.io/kubernetes-id: odeme-api
    pagerduty.com/integration-key: PD-KEY-BURAYA
    sonarqube.org/project-key: sirket_odeme-api
  tags:
    - java
    - spring-boot
    - odeme
    - tier-1
  links:
    - url: https://grafana.sirket.com/d/odeme-api
      title: Grafana Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: group:odeme-ekibi
  system: ödeme-sistemi
  providesApis:
    - odeme-v1
  dependsOn:
    - resource:odeme-db
    - resource:odeme-events-topic

Bu örnekte görüldüğü gibi, metadata bölümünde entity'nin adı, açıklaması ve çeşitli annotation'ları yer alır. Annotation'lar, Backstage'in hangi plugin'lerin aktif olacağını belirler. Örneğin backstage.io/kubernetes-id annotation'ı varsa, Kubernetes sekmesi otomatik olarak görüntülenir. spec bölümünde ise entity'nin tipi, yaşam döngüsü, sahibi ve ilişkileri tanımlanır.

Ownership Modeli ve Organizasyon Yapısı

Backstage'in en önemli prensiplerinden biri "her entity'nin bir sahibi olmalıdır" kuralıdır. Ownership modeli, organizasyon hiyerarşisini yansıtır ve sorumlulukları belirler. Bir component'in sahibi bir Group veya User olabilir. Group, bir ekibi veya departmanı temsil eder; User ise bireysel geliştiricileri ifade eder. Best practice olarak, component'lerin bireysel kullanıcılar yerine gruplara ait olması önerilir; bu sayede ekip değişikliklerinde ownership güncellemesi daha kolay yapılır.

Ownership hiyerarşisi, Backstage'in keşif ve izleme özelliklerinin temelini oluşturur. Bir geliştirici, herhangi bir servisin kime ait olduğunu, hangi sistemlerin birbiriyle ilişkili olduğunu ve bir arıza durumunda kiminle iletişime geçmesi gerektiğini portal üzerinden kolayca öğrenebilir.

Backstage Kurulumu ve Yapılandırması

Backstage'i kurmanın birden fazla yolu vardır; Docker, Kubernetes veya doğrudan Node.js çalıştırma seçenekleri mevcuttur. Kurulum sürecini adım adım inceleyelim.

Node.js ile Yerel Kurulum

Backstage, Node.js tabanlı bir uygulamadır. Öncelikle sisteminizde Node.js (18.x veya üzeri) ve npm'in kurulu olduğundan emin olunmalıdır. Kurulum için backstage-cli aracını kullanacağız.

# Backstage oluşturma
npx @backstage/create-app@latest my-backstage

# Oluşturulan dizine gitme
cd my-backstage

# Geliştirme sunucusunu başlatma
cd my-backstage && yarn dev

Bu komutlar, varsayılan yapılandırma ile hazır bir Backstage örneği oluşturur. Uygulama varsayılan olarak 3000 portunda çalışır ve tarayıcı üzerinden erişilebilir hale gelir.

Docker ile Kurulum

Üretim ortamında Docker kullanmak, izolasyon ve tutarlılık açısından avantajlıdır. Backstage'in resmi Docker image'ı mevcuttur ve kolayca kullanılabilir.

# Docker image oluşturma
docker build -t my-backstage .

# Container çalıştırma
docker run -p 3000:3000 my-backstage

Dockerfile, Backstage'in Node.js tabanlı yapısını paketler ve çalıştırılabilir bir container oluşturur.

Kubernetes Helm ile Kurulum

Kubernetes ortamında çalıştırmak isteyenler için resmi Helm chart mevcuttur. Bu yöntem, Helm paket yöneticisi kullanılarak tek komutla kurulum yapmanızı sağlar.

# Helm repository ekleme
helm repo add backstage https://backstage.github.io/helm-charts
helm repo update

# Backstage deploy etme
helm install my-backstage backstage/backstage \
  --namespace backstage \
  --create-namespace

Bu kurulum, Kubernetes cluster'ınızda Backstage pod'unu çalıştırır ve servis aracılığıyla erişilebilir kılar. Özel yapılandırma için configmap ve secret kullanarak ortam değişkenleri ve hassas bilgileri yönetebilirsiniz.

Yapılandırma Dosyaları ve Kimlik Doğrulama

Backstage'in doğru çalışması için app-config.yaml dosyasının uygun şekilde yapılandırılması gerekir. Bu dosya, catalog, auth, proxy ve plugin ayarlarını içerir.

Temel Yapılandırma

Aşağıda temel bir app-config.yaml yapılandırması görüyoruz.

app:
  title: Şirket Developer Portal
  baseUrl: https://backstage.sirket.com

catalog:
  locations:
    - type: url
      target: https://github.com/sirket/catalog-info.yaml
      rules:
        - allow: [Component, API, Resource, System, Domain, User, Group]
    - type: file
      target: ./catalog-entities.yaml

auth:
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: https://kubernetes.local
          name: production
          authProvider: serviceAccount
          skipTLSVerify: true

Bu yapılandırma, GitHub ile kimlik doğrulama, software catalog için location tanımları ve Kubernetes entegrasyonu ayarlarını içerir. Gerçek ortamda hassas bilgiler (API key'ler, secret'ler) ortam değişkenlerinden alınmalıdır.

GitHub Kimlik Doğrulaması

Kurumsal ortamda genellikle GitHub OAuth kullanılır. GitHub Developer Settings üzerinden yeni bir OAuth App oluşturmalı ve callback URL'sini doğru şekilde yapılandırmalısınız. Backstage, yetkili kullanıcıların kimliğini doğrulayarak kişiselleştirilmiş deneyim sunar ve entity'lerin ownership bilgisini GitHub kullanıcılarıyla eşleştirir.

TechDocs ile Dokümantasyon

TechDocs, Backstage'in yerleşik dokümantasyon çözümüdür. Markdown dosyalarınızı otomatik olarak HTML'e dönüştürür ve Backstage arayüzünde sunar. Bu yaklaşım, dokümantasyonun kodla birlikte yaşamasını sağlar; kod değiştikçe dokümantasyon da güncellenir.

TechDocs Kurulumu

TechDocs kullanmak için öncelikle Backstage'e plugin'in eklenmesi ve her repository'de mkdocs.yml dosyasının oluşturulması gerekir.

# Backstage app'e TechDocs plugin ekleme
cd my-backstage
yarn add @backstage/plugin-techdocs
yarn add @backstage/plugin-techdocs-backend

# Docker image'a mkdocs ekleme
echo RUN apk add mkdocs >> Dockerfile

Her repository'de ise şu dosyalar bulunmalıdır: docs/ klasörü içindeki Markdown dokümanlar, docs/index.md ana sayfası ve mkdocs.yml yapılandırma dosyası.

mkdocs.yml Yapılandırması

site_name: Ödeme API Dokümantasyonu
docs_dir: docs
site_dir: dist

nav:
  - Home: index.md
  - API Referansı:
      - Genel Bakış: api/overview.md
      - Endpoint Listesi: api/endpoints.md
  - Mimari: architecture.md

plugins:
  - techdocs-core

Bu yapılandırma ile TechDocs, docs klasöründeki Markdown dosyalarını okur ve Backstage üzerinde güzel bir dokümantasyon sitesi oluşturur.

Scaffolder ile Otomatik Proje Oluşturma

Scaffolder, geliştiricilerin standart şablonlar kullanarak yeni projeler oluşturmasını sağlar. Bu özellik, kurumsal standartların uygulanmasını ve yeni servislerin tutarlı bir yapıda başlatılmasını garanti eder.

Template Oluşturma

Bir template, STDIN (Template Definition) dosyası ve şablon dosyalarından oluşur. Aşağıda basit bir Node.js servis şablonu görüyoruz.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service-template
  title: Node.js Servis Şablonu
  description: Standart Node.js microservice yapısı
spec:
  owner: platform-ekibi
  type: service

  parameters:
    - title: Servis Bilgileri
      required:
        - componentName
        - description
      properties:
        componentName:
          title: Servis Adı
          type: string
        description:
          title: Açıklama
          type: string

  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:cookiecutter
      input:
        url: https://github.com/sirket/nodejs-service-template/archive/main.zip
        values:
          name: ${{ parameters.componentName }}
          description: ${{ parameters.description }}

    - id: publish
      name: Publish to Catalog
      action: catalog:register
      input:
        catalogInfoUrl: ${{ steps[fetch-base].output.catalogInfoUrl }}

Bu şablon, kullanıcıdan servis adı ve açıklaması alır, hazır bir template'i klonlar ve software catalog'a kaydeder.

Kubernetes Entegrasyonu

Backstage'in Kubernetes plugin'i, container orkestrasyon süreçlerini görselleştirir ve yönetim kolaylığı sağlar. Geliştiriciler, servislerinin Kubernetes üzerindeki durumunu portal üzerinden izleyebilir.

Plugin Kurulumu

# Kubernetes plugin ekleme
cd my-backstage
yarn add @backstage/plugin-kubernetes
yarn add @backstage/plugin-kubernetes-backend

Kubernetes plugin'in çalışması için bir service account oluşturulmalı ve uygun RBAC yetkileri verilmelidir.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: backstage-kubernetes
  namespace: backstage
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: backstage-kubernetes
rules:
  - apiGroups: [""]
    resources: [pods, services, configmaps]
    verbs: [get, list, watch]
  - apiGroups: [apps]
    resources: [deployments, replicasets]
    verbs: [get, list, watch]
  - apiGroups: [networking.k8s.io]
    resources: [ingresses]
    verbs: [get, list, watch]

Bu RBAC yapılandırması, Backstage'in Kubernetes cluster'ından bilgi okumasını sağlar. Hassas işlemler (pod silme, deployment güncelleme) için ek yetkiler gerekebilir.

En İyi Uygulamalar ve Başarılı Implementasyon

Backstage implementasyonu başarısı, doğru strateji ve uygulamalara bağlıdır. Kurumsal ortamda value yaratması için dikkat edilmesi gereken kritik noktalar vardır.

Catalog Governance ve Linting

Catalog'un güvenilirliği, içindeki verilerin doğruluğuna bağlıdır. Her repository'de catalog-info.yaml dosyasının geçerliliğini kontrol eden bir CI pipeline oluşturulmalıdır.

# package.json scripts
{
  scripts: {
    lint:catalog: backstage-cli repo lint --catalog-only
  }
}

# .github/workflows/catalog.yml
name: Catalog Validation
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: node/setup-node@v3
      - run: yarn install
      - run: yarn lint:catalog

Bu CI kontrolü, hatalı catalog dosyalarının ana branch'e girmesini engeller ve portalın güvenilirliğini korur.

Annotation Policy

Her organizasyon, hangi annotation'ların zorunlu olduğunu belirleyen bir policy oluşturmalıdır. Örneğin, üretim servislerinin mutlaka PagerDuty entegrasyonuna sahip olması veya her component'in TechDocs dokümantasyonunun bulunması gibi kurallar konulabilir. Bu policy'ler, Scorecard eklentileri ile uygulanabilir.

Adoption Strategy

Backstage'i tüm organizasyona yaymak, dikkatli bir değişim yönetimi gerektirir. Önce küçük bir pilot ekiple başlamak, değer kanıtlamak ve ardından kademeli olarak genişletmek önerilir. İlk aşamada sadece software catalog ve basit dokümantasyon ile başlanabilir; sonraki aşamalarda Scaffolder ve Kubernetes entegrasyonları eklenebilir.

Başarısız implementasyonların en yaygın nedeni "boş catalog" sorunudur. Entity'ler manuel olarak eklenmeye çalışıldığında veya otomatik keşif yapılmadığında, portal kısa sürede kullanılmaz hale gelir. Otomatik keşif mekanizmaları (GitHub webhook'ları, CI pipeline entegrasyonları) kurularak catalog'un sürekli güncel kalması sağlanmalıdır.

Sonuç

Backstage, platform mühendisliği alanında devrim niteliğinde bir araçtır. Doğru implementasyon ile geliştirici üretkenliğini önemli ölçüde artırır, dokümantasyonu kodla bütünleştirir ve altyapı yönetimini merkezi hale getirir. Ancak başarı, teknik kurulumun ötesinde organizasyonel stratejiye bağlıdır. Catalog'un değer yaratması için tüm ekiplerin katkıda bulunması ve güncel tutması gerekir. Bugün Backstage'i pilot bir proje ile denemeye başlayarak, organizasyonunuzun developer experience'ını önemli ölçüde iyileştirebilirsiniz.