DevOps 내부 개발자 플랫폼 플레이북 2026

# Backstage CLI로 신규 프로젝트 생성
npx @backstage/create-app@latest --skip-install

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

# 의존성 설치 및 실행
cd my-backstage
yarn install
yarn dev
# http://localhost:3000 에서 접속

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

organization:
  name: 'MyOrg'

backend:
  baseUrl: http://localhost: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}

# Software Catalog 설정
catalog:
  import:
    entityFilename: catalog-info.yaml
  rules:
    - allow: [Component, System, API, Resource, Location, Group, User]
  locations:
    # 조직의 모든 저장소에서 catalog-info.yaml 자동 탐색
    - type: github-discovery
      target: https://github.com/my-org/*/blob/main/catalog-info.yaml
    # 수동 등록
    - type: file
      target: ./catalog-entities/all-systems.yaml

# 인증 (GitHub OAuth)
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_OAUTH_CLIENT_ID}
        clientSecret: ${GITHUB_OAUTH_CLIENT_SECRET}

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: '주문 처리 마이크로서비스'
  annotations:
    github.com/project-slug: my-org/order-service
    backstage.io/techdocs-ref: dir:.
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/abc-123
    pagerduty.com/service-id: PXXXXXX
    argocd/app-name: order-service-prod
  tags:
    - java
    - spring-boot
    - tier-1
  links:
    - url: https://order.internal.example.com
      title: 프로덕션 URL
    - url: https://grafana.internal.example.com/d/order-service
      title: Grafana 대시보드
spec:
  type: service
  lifecycle: production
  owner: team-commerce
  system: commerce-platform
  dependsOn:
    - component:payment-service
    - resource:orders-database
  providesApis:
    - order-api
  consumesApis:
    - payment-api
    - inventory-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: '주문 REST API'
spec:
  type: openapi
  lifecycle: production
  owner: team-commerce
  definition:
    $text: ./docs/openapi.yaml

# templates/spring-boot-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: 'Spring Boot 마이크로서비스'
  description: 'CI/CD, 모니터링, 카탈로그가 자동 설정된 Spring Boot 서비스를 생성합니다'
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service
  parameters:
    - title: 서비스 정보
      required:
        - serviceName
        - ownerTeam
        - tier
      properties:
        serviceName:
          title: 서비스 이름
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
          description: '소문자, 숫자, 하이픈만 허용'
        ownerTeam:
          title: 소유 팀
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        tier:
          title: 서비스 티어
          type: string
          enum: ['tier-1', 'tier-2', 'tier-3']
          enumNames: ['Tier 1 (99.99% SLO)', 'Tier 2 (99.9% SLO)', 'Tier 3 (99% SLO)']
        javaVersion:
          title: Java 버전
          type: string
          default: '21'
          enum: ['17', '21']

    - title: 인프라 설정
      properties:
        database:
          title: 데이터베이스
          type: string
          default: 'postgresql'
          enum: ['postgresql', 'mysql', 'none']
        messageQueue:
          title: 메시지 큐
          type: string
          default: 'none'
          enum: ['kafka', 'rabbitmq', 'none']
        replicaCount:
          title: 기본 레플리카 수
          type: integer
          default: 3
          minimum: 1
          maximum: 20

  steps:
    # 1. 템플릿에서 저장소 생성
    - id: fetch-template
      name: 템플릿 코드 생성
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          ownerTeam: ${{ parameters.ownerTeam }}
          tier: ${{ parameters.tier }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}
          replicaCount: ${{ parameters.replicaCount }}

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

    # 3. ArgoCD 앱 등록
    - id: register-argocd
      name: ArgoCD 애플리케이션 등록
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}-prod
        argoInstance: main
        namespace: ${{ parameters.serviceName }}
        repoUrl: https://github.com/my-org/${{ parameters.serviceName }}
        path: k8s/overlays/production

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

  output:
    links:
      - title: 저장소
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: 카탈로그
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# mkdocs.yml (각 서비스 저장소 루트)
site_name: order-service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md
  - ADR:
      - adr/001-database-choice.md
      - adr/002-event-schema.md

plugins:
  - techdocs-core

<!-- docs/runbook.md -->

# Order Service 운영 런북

## 장애 대응

### 주문 처리 지연 (P95 > 500ms)

1. Grafana 대시보드 확인: [링크]
2. DB 커넥션 풀 상태 확인:

bash
kubectl exec -it deploy/order-service -- curl localhost:8080/actuator/metrics/hikaricp.connections.active

3. 커넥션 풀 포화 시:
   kubectl scale deploy/order-service --replicas=6

4. DB 슬로우 쿼리 확인:
   SELECT pid, now() - query_start AS duration, query
   FROM pg_stat_activity
   WHERE state = 'active' AND now() - query_start > interval '5s';

### 주문 생성 실패 (HTTP 500)

1. 에러 로그 확인:
   kubectl logs deploy/order-service --tail=100 | grep ERROR
2. 에러 코드별 대응:
   - ORDER-001: 결제 서비스 연결 실패 -> payment-service 상태 확인
   - ORDER-002: 재고 부족 -> inventory-service 동기화 확인
   - ORDER-003: DB 데드락 -> 트랜잭션 격리 수준 확인

# templates/provision-postgresql/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-postgresql
  title: 'PostgreSQL 데이터베이스 프로비저닝'
  description: 'RDS PostgreSQL 인스턴스를 셀프서비스로 생성합니다'
spec:
  owner: team-platform
  type: resource
  parameters:
    - title: 데이터베이스 설정
      required:
        - dbName
        - environment
        - instanceClass
      properties:
        dbName:
          title: DB 이름
          type: string
          pattern: '^[a-z][a-z0-9_]*$'
        environment:
          title: 환경
          type: string
          enum: ['dev', 'staging', 'production']
        instanceClass:
          title: 인스턴스 크기
          type: string
          default: 'db.r7g.large'
          enum:
            - 'db.t4g.medium'
            - 'db.r7g.large'
            - 'db.r7g.xlarge'
            - 'db.r7g.2xlarge'
          enumNames:
            - 'Small (2 vCPU, 4GB) - dev/staging'
            - 'Medium (2 vCPU, 16GB) - production'
            - 'Large (4 vCPU, 32GB) - production'
            - 'XLarge (8 vCPU, 64GB) - high traffic'
        storageGb:
          title: 스토리지 (GB)
          type: integer
          default: 100
          minimum: 20
          maximum: 16000
        multiAz:
          title: Multi-AZ 배포
          type: boolean
          default: false

  steps:
    - id: create-terraform-pr
      name: Terraform PR 생성
      action: publish:github:pull-request
      input:
        repoUrl: github.com?owner=my-org&repo=infrastructure
        branchName: provision-db-${{ parameters.dbName }}
        title: 'DB 프로비저닝: ${{ parameters.dbName }} (${{ parameters.environment }})'
        description: |
          자동 생성된 DB 프로비저닝 요청입니다.

          - DB 이름: ${{ parameters.dbName }}
          - 환경: ${{ parameters.environment }}
          - 인스턴스: ${{ parameters.instanceClass }}
          - 스토리지: ${{ parameters.storageGb }}GB
          - Multi-AZ: ${{ parameters.multiAz }}
        targetPath: terraform/rds/${{ parameters.environment }}/${{ parameters.dbName }}
        sourcePath: ./terraform-template

# platform_metrics.py - 플랫폼 KPI 대시보드 데이터 수집

import requests
from datetime import datetime, timedelta

class PlatformMetrics:
    def __init__(self, github_token: str, backstage_url: str):
        self.github = github_token
        self.backstage = backstage_url

    def service_creation_lead_time(self) -> dict:
        """신규 서비스 생성 소요 시간 (목표: 30분 이내)"""
        # Backstage scaffolder 로그에서 추출
        response = requests.get(
            f"{self.backstage}/api/scaffolder/v2/tasks",
            params={"createdAfter": (datetime.now() - timedelta(days=90)).isoformat()}
        )
        tasks = response.json()["items"]

        lead_times = []
        for task in tasks:
            if task["status"] == "completed":
                start = datetime.fromisoformat(task["createdAt"])
                end = datetime.fromisoformat(task["completedAt"])
                lead_times.append((end - start).total_seconds() / 60)

        return {
            "median_minutes": sorted(lead_times)[len(lead_times) // 2],
            "p95_minutes": sorted(lead_times)[int(len(lead_times) * 0.95)],
            "total_services_created": len(lead_times),
        }

    def golden_path_adoption_rate(self) -> dict:
        """골든패스 채택률 (목표: 80% 이상)"""
        # GitHub API에서 reusable workflow 사용 현황 조회
        repos = requests.get(
            "https://api.github.com/orgs/my-org/repos",
            headers={"Authorization": f"token {self.github}"},
            params={"per_page": 100, "type": "internal"}
        ).json()

        using_golden_path = 0
        total_active = 0

        for repo in repos:
            if repo["archived"]:
                continue
            total_active += 1
            # CI 워크플로우에서 골든패스 참조 확인
            workflows = requests.get(
                f"https://api.github.com/repos/my-org/{repo['name']}/actions/workflows",
                headers={"Authorization": f"token {self.github}"}
            ).json()

            for wf in workflows.get("workflows", []):
                if "golden" in wf.get("path", "").lower():
                    using_golden_path += 1
                    break

        return {
            "adoption_rate": using_golden_path / max(total_active, 1),
            "using_golden_path": using_golden_path,
            "total_active_repos": total_active,
        }

    def developer_nps(self) -> dict:
        """개발자 만족도 NPS (목표: 30 이상)"""
        # 분기별 서베이 결과 (Google Forms / Typeform 등)
        # 직접 API 연동하거나, 수동 입력
        return {
            "nps_score": 42,
            "promoters_pct": 55,
            "detractors_pct": 13,
            "response_rate": 0.72,
            "top_complaints": [
                "빌드 시간이 느림",
                "로그 검색 UI가 불편함",
                "권한 요청 자동화 부족",
            ]
        }

WARN: Entity refresh for component:order-service took 45s (threshold: 10s)

# 해결: 스캔 범위 제한 + 캐시 설정
catalog:
  providers:
    github:
      myOrg:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          repository: '^(?!archived-).*$' # archived- 접두사 저장소 제외
          topic:
            include: ['backstage-enabled'] # 토픽 기반 필터링
        schedule:
          frequency: { minutes: 30 } # 30분 주기 (기본 5분)
          timeout: { minutes: 5 }

Error: Resource not accessible by integration
HttpError: 403 - Resource not accessible by integration

# GitHub App 권한 확인
# Settings > Developer settings > GitHub Apps > [앱 이름] > Permissions
# 필요 권한:
# - Repository: Administration (Read & Write)
# - Repository: Contents (Read & Write)
# - Organization: Members (Read)
# 또는 Personal Access Token(PAT) 사용 시 필요 scope:
# repo, workflow, admin:org

mkdocs build failed: No module named 'techdocs_core'

# 해결: TechDocs 빌드 환경에 플러그인 설치
pip install mkdocs-techdocs-core

# Docker 빌드 사용 시
docker run --rm -v $(pwd):/content \
  spotify/techdocs:latest \
  build --site-dir /content/site

# app-config.yaml에서 빌드 방식 설정
# techdocs:
#   builder: 'external' # CI에서 빌드
#   publisher:
#     type: 'awsS3'
#     awsS3:
#       bucketName: 'my-org-techdocs'
#       region: 'ap-northeast-2'