🟡 Intermediate

Backstage — Internal Developer Portal

Backstage je open-source framework od Spotify na budovanie interných vývojárskych portálov (IDP — Internal Developer Portal). Nie je to hotový produkt, ktorý nainštalujete za päť minút — je to stavebnica, z ktorej si svoju platformu poskladáte sami. A práve toto je jeho najväčšia sila aj najväčší problém zároveň.

Backstage dnes beží v produkcii vo viac ako 3 000 organizáciách. V roku 2022 vstúpil do CNCF ako Incubating projekt a k aprílu 2026 zostáva v tejto fáze — CNCF graduation sa opakovane odkláda, hoci komunita naň aktívne pracuje. Napriek tomu je Backstage de facto štandard v kategórii open-source developer portálov a nemá skutočného open-source konkurenta na rovnakej úrovni vyspelosti.

Prečo Backstage vznikol a čo rieši

Spotify v roku 2016 prevádzkoval stovky microservices, ktoré spravovalo niekoľko stoviek vývojárov. Problém nebol technický — bol organizačný. Nikto nevedel:

  • Kto vlastní ktorú službu?
  • Kde sú jej logy, metriky, docs?
  • Aké API poskytuje a kto ho konzumuje?
  • Aká verzia runtime-u beží v produkcii?

Každý tím mal vlastný štandard, vlastný README, vlastnú wiki stránku. Keď nastúpil nový vývojár, orientácia trvala týždne. Spotify interný portál vyvinul okolo roku 2016, open-sourcoval ho v marci 2020 a odovzdal ho CNCF v septembri 2020.

Backstage rieši kognitívnu záťaž vývojárov cez tri hlavné nástroje:

  1. Software Catalog — centrálny register všetkých entít (služby, API, tímy, infraštruktúra).
  2. Software Templates (Scaffolder) — generovanie nových projektov z predlôh v súlade so štandardmi.
  3. TechDocs — dokumentácia priamo v repozitári, automaticky publikovaná do portálu.

Architektúra — frontend, backend, plugin model

Backstage má klasickú dvoj-vrstvovú architektúru:

┌─────────────────────────────────────────────┐
│  Browser                                    │
│  ┌─────────────────────────────────────┐   │
│  │  Backstage Frontend (React/TS)       │   │
│  │  Core UI + Plugin UIs                │   │
│  └─────────────────────────────────────┘   │
└────────────────────┬────────────────────────┘
                     │ HTTP / WebSocket
┌────────────────────▼────────────────────────┐
│  Backstage Backend (Node.js / TypeScript)   │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐ │
│  │ Catalog  │ │Scaffolder│ │  TechDocs   │ │
│  │ Backend  │ │ Backend  │ │  Backend    │ │
│  └────┬─────┘ └────┬─────┘ └──────┬──────┘ │
│       │             │              │         │
│  ┌────▼─────────────▼──────────────▼──────┐ │
│  │          PostgreSQL / SQLite           │ │
│  └────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Frontend je React aplikácia. Backstage v roku 2024 predstavil New Frontend System — deklaratívny plugin model cez extensions, ktorý nahradil starý imperatívny prístup. Verzia 1.42+ aktívne povzbudzuje migráciu. Ak dnes začínate nový Backstage deployment, použite nový frontend systém od začiatku.

Backend beží v Node.js a TypeScript. V roku 2023 prešiel rovnakou revolúciou — New Backend System nahradil starý inicializačný kód spaghetti. Stará architektúra bola odstránená; od verzie 1.40+ je nová povinná. Zabudnite na @backstage/backend-common a @backstage/backend-tasks — oba balíky sú deprecated a zmazané.

Plugin model je ústredný koncept. Každá funkcionalita je plugin — Catalog, Scaffolder, TechDocs, Kubernetes, ArgoCD. Plugin má typicky tri časti:

  • plugin-xyz — frontend UI
  • plugin-xyz-backend — backend logika, API
  • plugin-xyz-node — zdieľané typy a interfejsy

Software Catalog — srdce Backstage

Software Catalog je register entít definovaných cez YAML súbory (catalog-info.yaml) uložené priamo v repozitároch. Backstage pravidelne skenuje Git repozitáre (GitHub, GitLab, Bitbucket, Azure DevOps) a entít aktualizuje v databáze.

Typy entít

Kind Popis
Component Microservice, webová appka, knižnica, CLI nástroj
API OpenAPI, AsyncAPI, GraphQL, gRPC schéma
Resource Databáza, S3 bucket, managed služba
System Skupina komponentov tvoriaca logický celok
Domain Biznis doména združujúca systémy
Group Tím, organizačná jednotka
User Vývojár — importovaný z IdP (GitHub, Google, LDAP)
Template Scaffolder šablóna
Location Odkaz na ďalšie catalog-info súbory

Príklad: catalog-info.yaml pre microservice

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  title: Payment Service
  description: Spracovanie kreditných kariet a SEPA prevodov
  annotations:
    # GitHub integrácia
    github.com/project-slug: myorg/payment-service
    # TechDocs z koreňa repozitára
    backstage.io/techdocs-ref: dir:.
    # Kubernetes integrácia — pod selector
    backstage.io/kubernetes-id: payment-service
    backstage.io/kubernetes-namespace: production
    # ArgoCD aplikácia
    argocd/app-name: payment-service-prod
    # PagerDuty
    pagerduty.com/service-id: P123ABC
  tags:
    - nodejs
    - stripe
    - pci
  links:
    - url: https://grafana.internal/d/payment
      title: Grafana Dashboard
      icon: dashboard
    - url: https://runbook.internal/payment-service
      title: Runbook
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: group:team-payments
  system: checkout
  dependsOn:
    - component:user-service
    - component:fraud-detection-service
    - resource:payments-postgres-db
    - resource:payments-redis
  providesApis:
    - payments-api-v2
  consumesApis:
    - stripe-api
    - sendgrid-api

Vzťahy dependsOn, providesApis, consumesApis sú kľúčové — Backstage z nich generuje dependency graf celého systému. Toto je to, čo manažéri a architekti ocenia najviac.

TechDocs — dokumentácia ako kód

TechDocs je Backstage riešenie pre docs-as-code. Dokumentácia žije v repozitári (Markdown súbory), pri každom merge sa automaticky transformuje cez MkDocs a publikuje do Backstage portálu.

Minimálna konfigurácia v repozitári:

# mkdocs.yml
site_name: Payment Service
docs_dir: docs/
nav:
  - Prehľad: index.md
  - API: api.md
  - Runbook: runbook.md
  - Architecture Decision Records: adr/
plugins:
  - techdocs-core

TechDocs podporuje local aj external builder:

  • local — backend generuje dokumentáciu za behu (dobré pre dev/staging)
  • external — CI/CD pipeline generuje a uploaduje do S3/GCS, backend len servuje (povinné pre produkciu)

Pre produkciu vždy používajte external builder. Local builder blokuje backend, nevyzerá dobre pri väčšom počte docs-ov a neskaluje.

Software Templates — Scaffolder

Scaffolder je generátor nových projektov. Vývojár otvorí Backstage, vyberie template, vyplní formulár (názov služby, tím, databáza áno/nie, cloud region) a Backstage vytvorí repozitár, CI/CD pipeline, ArgoCD aplikáciu a záznam v Software Catalog — všetko automaticky.

Príklad: template.yaml pre Node.js microservice

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-microservice
  title: Node.js Microservice
  description: >
    Vytvorí nový Node.js microservice s Express, Docker,
    GitHub Actions CI/CD a ArgoCD deploymentom.
  tags:
    - nodejs
    - recommended
spec:
  owner: group:platform-team
  type: service

  parameters:
    - title: Základné informácie
      required: [name, owner, description]
      properties:
        name:
          title: Názov služby
          type: string
          description: Lowercase, bez medzier (napr. user-notifications)
          pattern: '^[a-z][a-z0-9-]*$'
        description:
          title: Popis
          type: string
        owner:
          title: Vlastníci (tím)
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group

    - title: Infraštruktúra
      properties:
        database:
          title: Databáza
          type: string
          default: none
          enum: [none, postgresql, redis]
          enumNames: [Bez databázy, PostgreSQL, Redis]
        environment:
          title: Cieľové prostredie
          type: string
          default: staging
          enum: [staging, production]

  steps:
    - id: fetch-template
      name: Stiahnutie šablóny
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          database: ${{ parameters.database }}

    - id: publish-github
      name: Vytvorenie GitHub repozitára
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
        defaultBranch: main
        repoVisibility: private
        topics:
          - microservice
          - nodejs

    - id: create-argocd-app
      name: Registrácia v ArgoCD
      action: argocd:create-resources
      input:
        appName: ${{ parameters.name }}-${{ parameters.environment }}
        argoInstance: production-cluster
        namespace: apps
        repoUrl: https://github.com/myorg/${{ parameters.name }}
        path: k8s/overlays/${{ parameters.environment }}

    - id: register-catalog
      name: Registrácia v Software Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: Repozitár
        url: ${{ steps['publish-github'].output.remoteUrl }}
      - title: ArgoCD
        url: https://argocd.internal/applications/${{ parameters.name }}-${{ parameters.environment }}
      - title: Backstage Catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

Scaffolder má bohatú sadu vstavaných actions: fetch:template, publish:github, publish:gitlab, catalog:register, github:actions:dispatch. Ďalšie actions pridávajú pluginy (ArgoCD, Kubernetes, Terraform). Vlastné actions napíšete v TypeScript.

Plugin ekosystém

Backstage plugin ekosystém je rozsiahly — na backstage.io/plugins je registrovaných stovky pluginov. Najdôležitejšie pre produkčné nasadenie:

Kubernetes plugin

Zobrazuje stav Kubernetes deploymentov priamo na stránke entity v katalógu. Vývojár vidí pody, rollout stav, logy a eventy bez otvárania kubectl.

# Anotácia v catalog-info.yaml pre Kubernetes plugin
metadata:
  annotations:
    backstage.io/kubernetes-id: payment-service
    backstage.io/kubernetes-namespace: production
    backstage.io/kubernetes-label-selector: 'app=payment-service'
    # Ak máte viacero klastrov:
    backstage.io/kubernetes-cluster: prod-eu-west-1

Kubernetes plugin vyžaduje konfiguráciu v app-config.yaml:

kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - name: prod-eu-west-1
          url: https://api.prod-eu-west-1.k8s.internal
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_SA_TOKEN}
          caData: ${K8S_CA_DATA}

ArgoCD plugin

Zobrazuje sync stav ArgoCD aplikácie, poslednú synced revíziu a zdravie aplikácie. Vývojár vidí priamo v Backstage, či bol jeho merge deploynutý a či je aplikácia Healthy.

GitHub Actions plugin

Zobrazuje zoznam CI/CD workflow runov, ich stav a logy. Vývojár nemusí chodiť na GitHub — vidí stav buildu priamo v kontexte svojej entity.

Cost Insights (Spotify plugin)

Komerčný plugin od Spotify (súčasť balíka Spotify Plugins for Backstage) zobrazuje cloud náklady per tím a per komponent. Integrácia s AWS Cost Explorer, GCP Billing, Azure Cost Management. Jeden z najcennejších pluginov pre veľké organizácie.

Ďalšie notable pluginy

  • Sonarqube — code quality metriky
  • Snyk / Dependabot — security insights, zraniteľnosti v závislostiach
  • PagerDuty — on-call informácie a incident história
  • Grafana — embeddované dashboardy priamo v entity stránke
  • Lighthouse — web performance audity
  • RBAC (community plugin, @backstage-community/plugin-rbac-backend) — fine-grained permissions UI

Inštalácia a prvé kroky

Vytvorenie projektu

npx @backstage/create-app@latest
# Interaktívny wizard sa opýta na názov
cd my-backstage-app

# Štart v dev móde (SQLite, bez autentifikácie)
yarn dev

Toto spustí Backstage na http://localhost:3000 s lokálnou SQLite databázou. Vhodné výhradne na lokálny vývoj.

Minimálna produkčná konfigurácia

# app-config.production.yaml
app:
  title: My Developer Portal
  baseUrl: https://backstage.internal.company.com

backend:
  baseUrl: https://backstage.internal.company.com
  listen:
    port: 7007

  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: 5432
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: backstage

catalog:
  providers:
    github:
      myOrg:
        organization: myorg
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: main
          repository: '.*'
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

  rules:
    - allow: [Component, API, Resource, System, Domain, Group, User, Template, Location]

auth:
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

techdocs:
  builder: external
  generator:
    runIn: local
  publisher:
    type: awsS3
    awsS3:
      bucketName: company-backstage-techdocs
      region: eu-west-1

Docker build a deploy

# Build Docker image (multi-stage, zabudovaný v create-app)
yarn build:backend
docker build -t backstage:$(git rev-parse --short HEAD) .

# Push do registry
docker tag backstage:abc123 registry.company.com/backstage:abc123
docker push registry.company.com/backstage:abc123

Identita a autorizácia

Backstage má vlastný Permissions Framework — flexibilný, ale komplexný systém, ktorý umožňuje pluginom deklarovať čo je chránené a integrátorovi definovať pravidlá.

Auth provideri

Backstage podporuje viacero OAuth/OIDC providerov out-of-the-box:

  • GitHub — najpoužívanejší, prepojenie na GitHub organizácie a tímy
  • Google — Workspace organizácie
  • Microsoft — Azure AD / Entra ID (vrátane group sync)
  • Okta, Auth0, OneLogin — cez OIDC/SAML adaptery
  • GitLab — GitLab OAuth
# app-config.yaml — GitHub auth
auth:
  environment: production
  session:
    secret: ${SESSION_SECRET}
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

RBAC a Permissions Framework

Základný Permissions Framework je súčasťou core — plugin deklaruje permissions, backend policy rozhoduje allow/deny. Pre vizuálnu správu RBAC cez UI existuje community plugin @backstage-community/plugin-rbac-backend.

RBAC plugin umožňuje bez kódu priradiť role skupinám a definovať, kto môže čo v katalógu robiť — kto môže spúšťať Scaffolder templates, kto môže mazať entity, kto má prístup k cost data.

Dôležité: Backstage nie je multi-tenant v plnom zmysle slova. Catalog je zdieľaný. Permissions framework umožňuje skryť entity alebo obmedziť akcie, ale nie je to náhrada za skutočnú tenancy izoláciu. Ak potrebujete tvrdú izoláciu medzi business unitmi, máte problém.

Produkčný deployment

Helm chart

Najjednoduchší deployment na Kubernetes je cez Helm chart. Backstage komunita udržiava chart backstage/backstage (publikovaný pod Backstage org na backstage.github.io/charts) — de-facto oficiálne riešenie:

helm repo add backstage https://backstage.github.io/charts
helm repo update

helm install backstage backstage/backstage \
  --namespace backstage \
  --create-namespace \
  --values backstage-values.yaml

# backstage-values.yaml
backstage:
  image:
    repository: registry.company.com/backstage
    tag: abc123
    pullPolicy: Always

  appConfig:
    app:
      baseUrl: https://backstage.internal.company.com
    backend:
      baseUrl: https://backstage.internal.company.com

  extraEnvVarsSecrets:
    - backstage-secrets

ingress:
  enabled: true
  className: nginx
  host: backstage.internal.company.com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod

postgresql:
  enabled: false   # VŽDY false pre produkciu — spravujte DB externe

serviceAccount:
  create: true
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789:role/backstage-role

PostgreSQL

Pre produkciu vždy používajte externý managed PostgreSQL (RDS, Cloud SQL, Azure Database). Backstage Helm chart obsahuje Bitnami PostgreSQL subchart — nepoužívajte ho v produkcii. Backstage generuje DB migrácie pri každom reštarte, čo je bezpečné, ale vyžaduje, aby DB connection bola vždy dostupná pred štartom.

Skalovanie

Backstage backend je stateless — môžete horizontálne škálovať repliky. Jediný caveat: Scaffolder tasks sú ukladané v DB, ale task execution je viazaný na konkrétnu inštanciu. Ak replika spadne počas behu template, task zostane stuck. Pre väčšie deploymenty používajte scaffolder.taskWorkers: multiple a dbajte na graceful shutdown.

Caddy / Nginx reverse proxy

# Caddyfile príklad
backstage.internal.company.com {
    tls internal
    reverse_proxy backstage-service.backstage.svc.cluster.local:7007
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
    }
}

Operačné úskalia a gotchas

Toto je sekcia, ktorú si prečítajte predtým, než sa rozhodnete nasadiť Backstage v produkcii.

1. DB migrácie a drift

Backstage robí automatické DB migrácie pri štarte. Problém nastáva pri downgrade — migrácie sú jednosmerné. Ak upgradnete Backstage, spustíte migráciu a potom sa rozhodnete vrátiť späť, DB schéma bude nekompatibilná so starším kódom. Nemáte rollback. Vždy zálohujte DB pred každým upgrádom.

Ďalší problém: pri pluginDivisionMode=schema (každý plugin má vlastnú DB schému namiesto vlastnej DB) môžu nastať konflikty migračných tabuliek (knex_migrations). Toto je známy bug a obídete ho tým, že každý plugin dostane vlastnú DB.

2. Plugin upgrade churn

Backstage vydáva main release každé 2-3 týždne. Každá verzia prináša breaking changes v pluginoch. Ak máte vlastné pluginy alebo forky community pluginov, upgrade sa stáva manuálnou prácou niekoľkých hodín. Tímy, ktoré zaostanú o 5+ verzií, majú vážny problém.

Riešenie: striktne sledujte changelogy, udržiavajte upgradovací rhythmus, ideálne raz za mesiac. Backstage poskytuje yarn backstage-cli versions:bump na automatické bumpovania package.json verzií.

3. Search výkon

Backstage má vstavaný search (Lunr pre in-memory, PostgreSQL full-text pre väčšie deploymentov). Pri tisícoch entít v katalógu PostgreSQL full-text search zaostáva. Pre veľké organizácie nasaďte Elasticsearch/OpenSearch plugin backend pre search.

4. Plugin sprawl

Backstage je ľahké rozšíriť pluginom. Je ťažké plugin odstrániť. Vývojári žiadajú "Grafana plugin", "Datadog plugin", "SonarQube plugin" — každý plugin je ďalší dependency, ďalší upgrade vektor, ďalší potenciálny zdroj regresie. Definujte jasný governance proces: nový plugin musí mať vlastníka, SLA, musí byť upgradovaný so zvyškom.

5. Catalog konzistencia

Backstage skenuje repozitáre pravidelne, nie v reálnom čase. Ak vývojár archivuje repozitár alebo premenuje entitu, katalóg bude zastaralý až do ďalšieho skenu. Backstage poskytuje webhooky pre GitHub/GitLab na triggrovanie okamžitého resync-u — nakonfigurujte ich.

6. Staré vs. nové systémy

Nový Backend System a New Frontend System nie sú spätne kompatibilné so starými pluginmi. Ak máte mix starých a nových pluginov, niektoré vyžadujú bridge wrappers. Cieľový stav je plná migrácia — neodkladajte ju, narastajúci tech debt v Backstage je obzvlášť bolestivý.

Alternatívy a kedy zvoliť čo

Nástroj Model Cena Vhodné pre
Backstage Open-source, self-hosted Free (ale 1-3 FTE na údržbu) 200+ vývojárov, dedikovaný platform tím
Port SaaS ~$78/mesiac základ 50-500 vývojárov, rýchly štart, bez DevOps kapacity na Backstage
Cortex SaaS ~$65/user/mesiac Štandardy, service maturity, ownership compliance
OpsLevel SaaS ~$39/user/mesiac 30-45 dní onboarding, ready-to-use out-of-the-box
Roadie Managed Backstage (SaaS) Kontaktujte Chcete Backstage bez infraštruktúrnej záťaže
Humanitec Platform Orchestrator (nie portal) Kontaktujte Infrastructure orchestration, Score manifesty

Port je najrýchlejší štart — vizuálna konfigurácia bez kódu, integrácie cez UI, predpripravené blueprinty. Ak váš tím nikdy nepostavi vlastný plugin, Port je pravdepodobne lepšia voľba ako Backstage.

Cortex a OpsLevel sa sústredia na service standards a ownership — skóre zdravia pre každú službu, koľko % services má runbook, monitoring, on-call. Toto Backstage nedáva out-of-the-box.

Roadie je Backstage-as-a-Service — dostanete Backstage, ale nemusíte sa starať o hosting, upgrady, DB. Pluginy konfigurujete cez UI. Kompromis medzi flexibilitou Backstage a jednoduchosťou SaaS.

Humanitec rieši iný problém — nie portál a katalóg, ale orchestráciu infraštruktúry cez Score manifesty. Môžete ho integrovať s Backstage (Humanitec plugin existuje).

Kedy NIE Backstage

Backstage je silný nástroj, ale nie pre každého. Vyhnite sa mu ak:

  • Máte menej ako 30-50 vývojárov. Overhead je príliš vysoký. Jednoduchý Confluence/Notion wiki + GitHub README pokrýva 90 % potrieb malého tímu.
  • Nemáte dedikovaný platform tím. Backstage vyžaduje neustálu údržbu — upgrady každé 2-3 týždne, plugin management, DB migrácie. Bez niekoho, kto to vlastní, Backstage rýchlo zaostane a stane sa nepoužiteľným.
  • Vaša organizácia má monolitickú architektúru. Software Catalog je navrhnutý pre stovky microservices, nie pre jeden monolit s jedným tímom.
  • Chcete výsledky do 30 dní. Produkčný Backstage deployment s autentifikáciou, Catalog integráciou, TechDocs a aspoň dvomi pluginmi trvá minimálne 6-8 týždňov. Ak potrebujete niečo rýchlejšie, pozrite sa na Port alebo OpsLevel.
  • Bezpečnostné požiadavky zakazujú self-hosted tooling. Backstage nemá komerčnú podporu — za security záplaty ste zodpovední sami.

Backstage v kontexte 2026

K aprílu 2026 je Backstage na verzii 1.42+ s aktívnou komunitou cez 2 000 prispievateľov a 3 000+ produkčných adopters. CNCF Graduation stále prebieha — Backstage splnil technické kritériá, graduácia je otázkou mesiaca či dvoch.

Red Hat vydáva Red Hat Developer Hub — enterprise distribúciu Backstage s komerčnou podporou. Ak vaša organizácia potrebuje SLA a enterprise support, toto je legitímna cesta.

Backstage BackstageCon na KubeCon EU 2026 v Amsterdame ukázal trend: komunita sa sústreďuje na New Frontend System adopciu, performance optimalizácie pre veľké katalógy a standardizáciu plugin API.

Zdroje