4장: 서비스 카탈로그와 소프트웨어 템플릿

apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: payment
  description: "결제 및 정산 도메인"
  annotations:
    backstage.io/techdocs-ref: dir:.
  tags:
    - payment
    - fintech
spec:
  owner: group:default/payment-division

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: checkout-system
  description: "결제 처리 시스템 - 주문, 결제, 영수증 발행"
  tags:
    - payment
    - checkout
spec:
  owner: group:default/checkout-team
  domain: payment

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: checkout-service
  description: "결제 처리 핵심 서비스"
  annotations:
    github.com/project-slug: mycompany/checkout-service
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/service-id: P1234567
    grafana/dashboard-selector: "checkout"
    sonarqube.org/project-key: mycompany_checkout-service
  tags:
    - java
    - spring-boot
    - grpc
  links:
    - url: https://grafana.mycompany.com/d/checkout
      title: "Grafana Dashboard"
      icon: dashboard
    - url: https://mycompany.atlassian.net/wiki/spaces/CHECKOUT
      title: "Confluence 문서"
      icon: docs
spec:
  type: service
  lifecycle: production
  owner: group:default/checkout-team
  system: checkout-system
  dependsOn:
    - resource:default/checkout-database
    - resource:default/payment-queue
    - component:default/user-service
  providesApis:
    - checkout-api
  consumesApis:
    - payment-gateway-api
    - notification-api

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: checkout-api
  description: "결제 처리 REST API"
  tags:
    - rest
    - payment
spec:
  type: openapi
  lifecycle: production
  owner: group:default/checkout-team
  system: checkout-system
  definition:
    $text: ./openapi.yaml

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: checkout-database
  description: "결제 데이터 저장용 PostgreSQL"
  annotations:
    mycompany.com/cloud-resource-id: "rds:ap-northeast-2:checkout-db"
  tags:
    - postgresql
    - rds
spec:
  type: database
  lifecycle: production
  owner: group:default/checkout-team
  system: checkout-system
  dependencyOf:
    - component:default/checkout-service

conventions:
  component_name:
    pattern: "[a-z][a-z0-9-]*"
    examples:
      good: ["user-service", "payment-gateway", "auth-library"]
      bad: ["UserService", "payment_gateway", "auth lib"]
 
  system_name:
    pattern: "[a-z][a-z0-9-]*-system"
    examples:
      good: ["checkout-system", "user-management-system"]
      bad: ["checkout", "UserManagement"]
 
  api_name:
    pattern: "[a-z][a-z0-9-]*-api"
    examples:
      good: ["checkout-api", "user-api"]
      bad: ["checkoutAPI", "user_api"]
 
  tags:
    categories:
      language: ["java", "kotlin", "go", "python", "typescript"]
      framework: ["spring-boot", "gin", "fastapi", "nestjs"]
      protocol: ["rest", "grpc", "graphql", "async-api"]
      criticality: ["tier-1", "tier-2", "tier-3"]

required_annotations:
  all_components:
    - key: "github.com/project-slug"
      description: "GitHub 저장소 경로"
      example: "mycompany/checkout-service"
 
    - key: "backstage.io/techdocs-ref"
      description: "TechDocs 문서 위치"
      example: "dir:."
 
  production_services:
    - key: "pagerduty.com/service-id"
      description: "PagerDuty 서비스 ID"
      example: "P1234567"
 
    - key: "mycompany.com/tier"
      description: "서비스 중요도 등급"
      example: "tier-1"
 
    - key: "mycompany.com/slo-target"
      description: "SLO 목표 가용성"
      example: "99.9%"

name: Catalog Validation
 
on:
  pull_request:
    paths:
      - "catalog-info.yaml"
 
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Validate catalog-info.yaml
        run: |
          npx @backstage/cli catalog-info validate catalog-info.yaml
 
      - name: Check required annotations
        run: |
          python scripts/check-annotations.py catalog-info.yaml
 
      - name: Check naming conventions
        run: |
          python scripts/check-naming.py catalog-info.yaml

catalog:
  providers:
    github:
      myCompanyOrg:
        organization: mycompany
        catalogPath: /catalog-info.yaml
        filters:
          branch: main
          repository: ".*"
        schedule:
          frequency:
            minutes: 30
          timeout:
            minutes: 3

# Kubernetes Deployment에 Backstage 어노테이션 추가
apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout-service
  annotations:
    backstage.io/kubernetes-id: checkout-service
    backstage.io/kubernetes-namespace: checkout
    backstage.io/kubernetes-label-selector: "app=checkout-service"

templates/
  spring-boot-service/
    template.yaml          # 템플릿 정의
    skeleton/              # 프로젝트 스켈레톤
      catalog-info.yaml
      mkdocs.yml
      docs/
        index.md
      src/
        main/
          java/...
        test/
          java/...
      build.gradle
      Dockerfile
      .github/
        workflows/
          ci.yaml

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: "Spring Boot 마이크로서비스"
  description: "표준 Spring Boot 마이크로서비스를 생성합니다. CI/CD, 모니터링, TechDocs가 사전 구성됩니다."
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: group:default/platform-team
  type: service
 
  parameters:
    - title: "서비스 기본 정보"
      required:
        - serviceName
        - description
        - owner
        - system
      properties:
        serviceName:
          title: "서비스 이름"
          type: string
          description: "소문자, 하이픈 구분 (예: checkout-service)"
          pattern: "^[a-z][a-z0-9-]*$"
          ui:autofocus: true
        description:
          title: "서비스 설명"
          type: string
          description: "이 서비스가 하는 일을 간략히 설명하세요"
        owner:
          title: "소유 팀"
          type: string
          description: "서비스를 관리하는 팀"
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        system:
          title: "시스템"
          type: string
          description: "이 서비스가 속하는 시스템"
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System
 
    - title: "기술 옵션"
      properties:
        javaVersion:
          title: "Java 버전"
          type: string
          enum: ["21", "17"]
          default: "21"
        springBootVersion:
          title: "Spring Boot 버전"
          type: string
          enum: ["3.4.x", "3.3.x"]
          default: "3.4.x"
        database:
          title: "데이터베이스"
          type: string
          enum: ["postgresql", "mysql", "none"]
          default: "postgresql"
        messaging:
          title: "메시징"
          type: string
          enum: ["kafka", "rabbitmq", "none"]
          default: "none"
 
    - title: "인프라 옵션"
      properties:
        environment:
          title: "배포 환경"
          type: array
          items:
            type: string
            enum: ["dev", "staging", "production"]
          default: ["dev", "staging", "production"]
          uniqueItems: true
        tier:
          title: "서비스 등급"
          type: string
          enum: ["tier-1", "tier-2", "tier-3"]
          default: "tier-3"
          description: "tier-1: 핵심 서비스, tier-2: 중요 서비스, tier-3: 일반 서비스"
 
  steps:
    - id: fetch-skeleton
      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 }}
 
    - id: create-repo
      name: "GitHub 저장소 생성"
      action: publish:github
      input:
        repoUrl: "github.com?owner=mycompany&repo=${{ parameters.serviceName }}"
        description: ${{ parameters.description }}
        defaultBranch: main
        protectDefaultBranch: true
        repoVisibility: internal
 
    - id: register-catalog
      name: "카탈로그에 등록"
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['create-repo'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
 
    - id: create-argocd-app
      name: "ArgoCD 앱 생성"
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}
        argoInstance: main
        namespace: ${{ parameters.serviceName }}
        repoUrl: ${{ steps['create-repo'].output.remoteUrl }}
        path: k8s/overlays/dev
 
  output:
    links:
      - title: "GitHub 저장소"
        url: ${{ steps['create-repo'].output.remoteUrl }}
      - title: "카탈로그 페이지"
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.serviceName }}
  description: "${{ values.description }}"
  annotations:
    github.com/project-slug: "mycompany/${{ values.serviceName }}"
    backstage.io/techdocs-ref: dir:.
    mycompany.com/tier: "${{ values.tier }}"
  tags:
    - java
    - spring-boot
spec:
  type: service
  lifecycle: production
  owner: ${{ values.owner }}
  system: ${{ values.system }}

import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
 
export function createSlackChannelAction() {
  return createTemplateAction<{
    channelName: string;
    description: string;
    teamMembers: string[];
  }>({
    id: 'mycompany:slack:create-channel',
    schema: {
      input: {
        required: ['channelName'],
        type: 'object',
        properties: {
          channelName: {
            type: 'string',
            title: 'Slack 채널 이름',
          },
          description: {
            type: 'string',
            title: '채널 설명',
          },
          teamMembers: {
            type: 'array',
            items: { type: 'string' },
            title: '초대할 팀원 이메일',
          },
        },
      },
    },
    async handler(ctx) {
      const { channelName, description, teamMembers } = ctx.input;
 
      ctx.logger.info(
        `Creating Slack channel: #${channelName}`,
      );
 
      // Slack API를 호출하여 채널 생성
      const response = await fetch('https://slack.com/api/conversations.create', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.SLACK_BOT_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: channelName,
          is_private: false,
        }),
      });
 
      const data = await response.json();
 
      if (!data.ok) {
        throw new Error(
          `Slack 채널 생성 실패: ${data.error}`,
        );
      }
 
      ctx.logger.info(
        `Slack channel created: ${data.channel.id}`,
      );
 
      ctx.output('channelId', data.channel.id);
      ctx.output('channelUrl', `https://mycompany.slack.com/archives/${data.channel.id}`);
    },
  });
}

steps:
  # ... 기존 스텝 ...
 
  - id: create-slack-channel
    name: "Slack 채널 생성"
    action: mycompany:slack:create-channel
    input:
      channelName: "svc-${{ parameters.serviceName }}"
      description: "${{ parameters.description }}"
      teamMembers: ${{ parameters.teamMembers }}