Backstage Developer Portal 구축 — 사내 표준화 30일 로드맵

핵심 요약

회사 규모가 커지면 "이 서비스는 누가 운영하지?", "어떻게 새 서비스 시작하지?", "문서는 어디 있지?" 가 일상이 된다. Backstage는 이 모든 답을 한 페이지로 모은 개발자 포털 (Internal Developer Portal·IDP).

• Spotify에서 만들고 CNCF Incubating
• 2026년 시점 1만+ 회사 운영
• 핵심 4축: Catalog, Docs, Templates, Plugins

1. 무엇을 해결하나

2. Day 1~3 — 셋업

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

# 데이터베이스 (PostgreSQL)
# config: app-config.yaml
backend:
  database:
    client: pg
    connection:
      host: postgres
      database: backstage
      user: ...
      password: ...

# 시작
yarn dev
# http://localhost:3000

3. Day 4~7 — Service Catalog

모든 서비스를 catalog-info.yaml로 등록.

# catalog-info.yaml (서비스 저장소 루트)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: 주문 처리 서비스
  annotations:
    github.com/project-slug: myorg/order-service
    pagerduty.com/service-id: P12345
    grafana.com/dashboard-selector: app=order-service
  tags: ['backend', 'tier1']
spec:
  type: service
  lifecycle: production
  owner: payment-team
  system: orders
  dependsOn:
    - resource:postgres-orders
    - component:user-service

# GitHub 자동 등록
# app-config.yaml
catalog:
  providers:
    github:
      myorg-repos:
        organization: 'myorg'
        catalogPath: '/catalog-info.yaml'
        schedule:
          frequency: PT5M

5분 간격으로 모든 repo 스캔, catalog-info.yaml 발견 시 자동 등록.

4. Day 8~14 — TechDocs

# 서비스 저장소 구조
├── catalog-info.yaml
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── architecture.md
    └── runbook.md

# catalog-info.yaml
metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

# Backstage가 자동으로 build·serve

Markdown 문서가 자동으로 검색 가능한 사이트로. 코드와 함께 docs도 PR로 관리.

5. Day 15~21 — Software Templates

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-microservice
  title: Node.js 마이크로서비스
spec:
  parameters:
    - title: 기본 정보
      properties:
        name: { type: string }
        owner: { type: string, ui:field: OwnerPicker }
  steps:
    - id: fetch
      action: fetch:template
      input:
        url: ./skeleton
        values: { name: ${{ parameters.name }} }
    
    - id: publish
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
    
    - id: register
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

"Create Component" 버튼 클릭 → 양식 작성 → GitHub repo 자동 생성 + Catalog 등록 + CI 설정 + 첫 PR 자동 생성.

6. Day 22~30 — 통합 플러그인

핵심 플러그인 5개

# GitHub Actions
yarn add @backstage/plugin-github-actions

# Kubernetes (Pod 상태)
yarn add @backstage/plugin-kubernetes

# Grafana 임베드
yarn add @backstage/plugin-grafana

# PagerDuty
yarn add @backstage/plugin-pagerduty

# Cost Insights (FinOps)
yarn add @backstage/plugin-cost-insights

각 서비스 카드에 통합 표시

• 최근 deployments (GitHub Actions)
• 현재 Pod 상태 (Kubernetes)
• 대시보드 임베드 (Grafana)
• 온콜 정보 (PagerDuty)
• 이번 달 비용

7. 인증·RBAC

# app-config.yaml
auth:
  providers:
    github:
      development:
        clientId: ...
        clientSecret: ...
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

# RBAC
permission:
  enabled: true
  rbac:
    admin:
      users:
        - user:default/admin@company.com

8. 검색 통합

# Postgres 기반 검색 (간단)
# 또는 ElasticSearch (대규모)

search:
  pg:
    highlightOptions:
      preTag: '<mark>'
      postTag: '</mark>'

Catalog·TechDocs·플러그인 데이터 모두 통합 검색. 단축키 Cmd+K.

9. Software Catalog 시각화

System·Component 관계가 자동 다이어그램. 의존성 추적·영향도 분석에 강력.

10. 운영 — production 베스트 프랙티스

• PostgreSQL HA — Backstage가 SPOF 되면 안 됨
• Backstage 자체도 Kubernetes에 deploy
• 매일 catalog 동기화 + drift 알림
• plugin은 신중하게 — 너무 많으면 UX 저하
• 커스텀 plugin은 monorepo 내부 packages/

11. 도입 효과 (실측, 100+ 서비스 회사)

12. 대안

자주 묻는 질문

회사 크기 어느 정도부터 도입 가치?서비스 20개 또는 개발자 50명 이상부터 효과. 그 이하는 README + Notion이 더 단순.

운영 부담?1명 풀타임 또는 2명 50%. plugins 통합·custom 작업 등.

Backstage Self-hosted vs SaaS Port?customization 필요·예산 부족 → Backstage. 빠른 시작·운영 안 하고 싶음 → Port.