Platform Engineering과 Backstage로 Internal Developer Platform 구축 실전 가이드

┌──────────────────────────────────────────────────────┐
│                 Developer Portal (UI)                 │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │  Catalog  │ │  Scaffolder│ │  TechDocs         │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
├──────────────────────────────────────────────────────┤
│            Internal Developer Platform                │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │ IaC Engine│ │ CI/CD     │ │ Policy Engine     │  │
│   │ (Terraform│ │ (GitHub   │ │ (OPA/Kyverno)     │  │
│   │  Crossplane│ │  Actions) │ │                   │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
│   ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
│   │ K8s       │ │ Observ-   │ │ Secret Mgmt       │  │
│   │ Clusters  │ │ ability   │ │ (Vault)           │  │
│   └───────────┘ └───────────┘ └───────────────────┘  │
└──────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│              Backstage App (React)               │
│  ┌─────────┐ ┌──────────┐ ┌─────────────────┐   │
│  │ Catalog │ │ Scaffolder│ │ TechDocs        │   │
│  │ Plugin  │ │ Plugin   │ │ Plugin          │   │
│  └─────────┘ └──────────┘ └─────────────────┘   │
│  ┌─────────┐ ┌──────────┐ ┌─────────────────┐   │
│  │ K8s     │ │ CI/CD    │ │ Custom Plugins  │   │
│  │ Plugin  │ │ Plugin   │ │                 │   │
│  └─────────┘ └──────────┘ └─────────────────┘   │
├─────────────────────────────────────────────────┤
│           Backstage Backend (Node.js)            │
│  ┌──────────┐ ┌───────────┐ ┌────────────────┐  │
│  │ Catalog  │ │ Scaffolder│ │ Auth Provider  │  │
│  │ Backend  │ │ Backend  │ │ (GitHub/Okta)  │  │
│  └──────────┘ └───────────┘ └────────────────┘  │
├─────────────────────────────────────────────────┤
│         Database (PostgreSQL) / Search           │
└─────────────────────────────────────────────────┘

# Backstage 앱 생성
npx @backstage/create-app@latest

# 프로젝트 디렉토리 구조
# my-backstage-app/
# ├── app-config.yaml           # 메인 설정 파일
# ├── app-config.production.yaml # 프로덕션 오버라이드
# ├── catalog-info.yaml         # Backstage 자체의 카탈로그 엔트리
# ├── packages/
# │   ├── app/                  # 프론트엔드 (React)
# │   └── backend/              # 백엔드 (Node.js)
# ├── plugins/                  # 커스텀 플러그인
# └── package.json

# 로컬 개발 서버 시작
cd my-backstage-app
yarn dev

# app-config.yaml
app:
  title: 'ACME Developer Platform'
  baseUrl: http://localhost:3000

organization:
  name: 'ACME Corp'

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

# GitHub 통합 설정
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# 인증 프로바이더 설정
auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

# 카탈로그 소스 등록
catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Template, Group, User]
  locations:
    # 조직 전체 GitHub 저장소 자동 탐색
    - type: github-discovery
      target: https://github.com/acme-corp/*/blob/main/catalog-info.yaml
    # 템플릿 등록
    - type: file
      target: ../../templates/all-templates.yaml
    # 조직 구조 동기화
    - type: github-org
      target: https://github.com/acme-corp

# app-config.production.yaml
app:
  baseUrl: https://developer.acme.com

backend:
  baseUrl: https://developer-api.acme.com
  cors:
    origin: https://developer.acme.com

# TechDocs를 외부 스토리지로 설정
techdocs:
  builder: 'external'
  generator:
    runIn: 'local'
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'acme-techdocs'
      region: 'ap-northeast-2'

# catalog-info.yaml - 마이크로서비스 등록 예시
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  title: '주문 서비스'
  description: '주문 생성, 결제 처리, 재고 차감을 담당하는 핵심 도메인 서비스'
  annotations:
    # GitHub 연동
    github.com/project-slug: acme-corp/order-service
    # CI/CD 연동
    backstage.io/techdocs-ref: dir:.
    github.com/workflows: build-and-deploy.yaml
    # Kubernetes 연동
    backstage.io/kubernetes-id: order-service
    backstage.io/kubernetes-namespace: order
    # PagerDuty 인시던트 연동
    pagerduty.com/service-id: PXXXXXX
    # Datadog 대시보드
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/xxx
  tags:
    - java
    - spring-boot
    - grpc
  links:
    - url: https://grafana.acme.com/d/order-svc
      title: 'Grafana Dashboard'
      icon: dashboard
    - url: https://wiki.acme.com/order-domain
      title: 'Domain Wiki'
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  providesApis:
    - order-api
  consumesApis:
    - inventory-api
    - payment-api
  dependsOn:
    - resource:order-database
    - resource:order-redis
---
# API 명세 등록
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: '주문 처리 gRPC API'
spec:
  type: grpc
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  definition:
    $text: ./proto/order.proto
---
# 데이터베이스 리소스 등록
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: order-database
  description: '주문 서비스 PostgreSQL 데이터베이스'
spec:
  type: database
  owner: team-order
  system: ecommerce-platform

# templates/spring-boot-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-grpc-service
  title: 'Spring Boot gRPC 마이크로서비스'
  description: |
    Spring Boot 3.x + gRPC 기반 마이크로서비스 프로젝트를 생성합니다.
    포함 항목: Dockerfile, Helm Chart, GitHub Actions CI/CD,
    Prometheus 메트릭, Health Check, catalog-info.yaml
  tags:
    - java
    - spring-boot
    - grpc
    - recommended
spec:
  owner: platform-team
  type: service

  # 사용자 입력 파라미터 정의
  parameters:
    - title: '서비스 기본 정보'
      required:
        - serviceName
        - owner
        - system
      properties:
        serviceName:
          title: '서비스 이름'
          type: string
          description: '영문 소문자, 하이픈만 사용 (예: order-service)'
          pattern: '^[a-z][a-z0-9-]*$'
          ui:autofocus: true
        description:
          title: '서비스 설명'
          type: string
        owner:
          title: '소유 팀'
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        system:
          title: '소속 시스템'
          type: string
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System

    - title: '기술 옵션'
      properties:
        javaVersion:
          title: 'Java 버전'
          type: string
          enum: ['17', '21']
          default: '21'
        database:
          title: '데이터베이스'
          type: string
          enum: ['postgresql', 'mysql', 'none']
          default: 'postgresql'
        enableKafka:
          title: 'Kafka 연동'
          type: boolean
          default: false

    - title: '인프라 설정'
      properties:
        namespace:
          title: 'K8s 네임스페이스'
          type: string
          default: 'default'
        cluster:
          title: '배포 클러스터'
          type: string
          enum: ['dev', 'staging', 'production']
          default: 'dev'

  # 실행 단계 정의
  steps:
    # 1. 템플릿에서 프로젝트 코드 생성
    - id: fetch-template
      name: '프로젝트 코드 생성'
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          system: ${{ parameters.system }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}
          enableKafka: ${{ parameters.enableKafka }}
          namespace: ${{ parameters.namespace }}

    # 2. GitHub 저장소 생성
    - id: publish-github
      name: 'GitHub 저장소 생성'
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=acme-corp&repo=${{ parameters.serviceName }}
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true
        requireCodeOwnerReviews: true
        repoVisibility: internal

    # 3. Backstage 카탈로그에 등록
    - id: register-catalog
      name: '카탈로그 등록'
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    # 4. ArgoCD Application 생성
    - id: create-argocd-app
      name: 'ArgoCD 배포 설정'
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}
        argoInstance: main
        namespace: ${{ parameters.namespace }}
        repoUrl: ${{ steps['publish-github'].output.remoteUrl }}
        path: deploy/helm

  # 완료 후 안내
  output:
    links:
      - title: 'GitHub 저장소'
        url: ${{ steps['publish-github'].output.remoteUrl }}
      - title: '카탈로그에서 보기'
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# 프론트엔드 플러그인 생성
cd my-backstage-app
yarn new --select plugin

# 백엔드 플러그인 생성
yarn new --select backend-plugin

# 생성된 플러그인 구조
# plugins/
# └── my-custom-plugin/
#     ├── src/
#     │   ├── components/
#     │   │   └── ExampleComponent/
#     │   ├── plugin.ts          # 플러그인 정의
#     │   ├── routes.ts          # 라우팅 설정
#     │   └── index.ts
#     ├── dev/                   # 독립 개발 환경
#     │   └── index.tsx
#     └── package.json

// plugins/team-health-dashboard/src/plugin.ts
import { createPlugin, createRoutableExtension } from '@backstage/core-plugin-api'

export const teamHealthDashboardPlugin = createPlugin({
  id: 'team-health-dashboard',
  routes: {
    root: rootRouteRef,
  },
})

export const TeamHealthDashboardPage = teamHealthDashboardPlugin.provide(
  createRoutableExtension({
    name: 'TeamHealthDashboardPage',
    component: () => import('./components/DashboardPage').then((m) => m.DashboardPage),
    mountPoint: rootRouteRef,
  })
)

// plugins/team-health-dashboard/src/components/DashboardPage.tsx
import React, { useEffect, useState } from 'react';
import {
  Table,
  TableColumn,
  StatusOK,
  StatusError,
  StatusWarning,
  Progress,
  ResponseErrorPanel,
} from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import { catalogApiRef } from '@backstage/plugin-catalog-react';

interface ServiceHealth {
  name: string;
  owner: string;
  status: 'healthy' | 'degraded' | 'down';
  uptime: number;
  lastIncident: string;
  errorRate: number;
}

const columns: TableColumn<ServiceHealth>[] = [
  { title: '서비스', field: 'name' },
  { title: '소유팀', field: 'owner' },
  {
    title: '상태',
    field: 'status',
    render: (row: ServiceHealth) => {
      switch (row.status) {
        case 'healthy':
          return <StatusOK>정상</StatusOK>;
        case 'degraded':
          return <StatusWarning>성능 저하</StatusWarning>;
        case 'down':
          return <StatusError>장애</StatusError>;
        default:
          return null;
      }
    },
  },
  { title: 'Uptime (%)', field: 'uptime', type: 'numeric' },
  { title: '에러율 (%)', field: 'errorRate', type: 'numeric' },
  { title: '마지막 인시던트', field: 'lastIncident' },
];

export const DashboardPage = () => {
  const catalogApi = useApi(catalogApiRef);
  const [services, setServices] = useState<ServiceHealth[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error>();

  useEffect(() => {
    const fetchData = async () => {
      try {
        const entities = await catalogApi.getEntities({
          filter: { kind: 'Component', 'spec.type': 'service' },
        });

        // 각 서비스의 헬스 데이터를 Prometheus/Datadog API에서 가져오기
        const healthData = await Promise.all(
          entities.items.map(async entity => {
            const metrics = await fetchServiceMetrics(
              entity.metadata.name,
            );
            return {
              name: entity.metadata.name,
              owner:
                entity.spec?.owner?.toString() ?? 'unknown',
              status: metrics.status,
              uptime: metrics.uptime,
              lastIncident: metrics.lastIncident,
              errorRate: metrics.errorRate,
            };
          }),
        );

        setServices(healthData);
      } catch (e) {
        setError(e as Error);
      } finally {
        setLoading(false);
      }
    };

    fetchData();
  }, [catalogApi]);

  if (loading) return <Progress />;
  if (error) return <ResponseErrorPanel error={error} />;

  return (
    <Table
      title="서비스 헬스 대시보드"
      columns={columns}
      data={services}
      options={{
        sorting: true,
        paging: true,
        pageSize: 20,
        search: true,
      }}
    />
  );
};

# 1. 현재 버전 확인
yarn backstage-cli info

# 2. 버전 범프 (의존성 자동 업데이트)
yarn backstage-cli versions:bump

# 3. 변경사항 확인
git diff

# 4. 타입 체크
yarn tsc

# 5. 테스트 실행
yarn test

# 6. 빌드 확인
yarn build

# 7. 마이그레이션 가이드 확인
# https://backstage.io/docs/getting-started/keeping-backstage-updated

# 권장: CI에서 자동으로 업그레이드 PR 생성
# .github/workflows/backstage-upgrade.yaml
# 매주 월요일 자동 실행하여 버전 범프 후 PR 생성

# app-config.yaml - 연결 풀 튜닝
backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
    pool:
      min: 5
      max: 30
      acquireTimeoutMillis: 60000
      idleTimeoutMillis: 30000