Backstage 골든 패스(Golden Path) 템플릿: 보안과 CI/CD가 내장된 서비스를 처음부터 만드는 법

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-service
  title: Node.js 백엔드 서비스
  description: 조직 표준이 적용된 Node.js 서비스를 생성합니다
spec:
  owner: platform-team
  type: service
 
  # 1. Parameters: 개발자가 UI에서 입력하는 값들
  parameters:
    - title: 서비스 정보
      required: [name, owner]
      properties:
        name:
          type: string
          title: 서비스 이름
          pattern: '^[a-z][a-z0-9-]*$'
        owner:
          type: string
          title: 소유 팀
          ui:field: OwnerPicker
 
  # 2. Steps: 실제 실행되는 액션 목록
  steps:
    - id: fetch
      name: 코드 스캐폴딩
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
 
    - id: publish
      name: GitHub 저장소 생성
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
        defaultBranch: main
        protectDefaultBranch: true
 
    - id: register
      name: 카탈로그 등록
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
 
  # 3. Outputs: 완료 후 보여줄 링크들
  outputs:
    - id: remoteUrl
      title: 저장소 URL
      url: ${{ steps.publish.output.remoteUrl }}

my-template/
├── template.yaml
└── skeleton/
    ├── catalog-info.yaml
    ├── .github/
    │   └── workflows/
    │       └── ci.yaml
    ├── Dockerfile
    └── src/
        └── index.ts

# skeleton/catalog-info.yaml
# 스켈레톤 파일 안에서는 Nunjucks 문법 사용 (달러 기호 없음)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: {{ values.name }}
  annotations:
    github.com/project-slug: myorg/{{ values.name }}
spec:
  type: service
  lifecycle: production
  owner: {{ values.owner }}

# template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: nodejs-golden-path
  title: Node.js 서비스 (골든 패스)
spec:
  owner: platform-team
  type: service
  parameters:
    - title: 서비스 정보
      required: [name, owner, description]
      properties:
        name:
          type: string
          title: 서비스 이름
          description: 소문자, 숫자, 하이픈만 사용 가능합니다
          pattern: '^[a-z][a-z0-9-]{2,30}$'
        owner:
          type: string
          title: 소유 팀
          ui:field: OwnerPicker
        description:
          type: string
          title: 서비스 설명
        enableDatabase:
          type: boolean
          title: PostgreSQL 연결이 필요한가요?
          default: false
 
  steps:
    - id: fetch
      name: 코드 생성
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}
          description: ${{ parameters.description }}
          enableDatabase: ${{ parameters.enableDatabase }}
 
    - id: publish
      name: GitHub 저장소 생성
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.name }}
        defaultBranch: main
        protectDefaultBranch: true
        topics:
          - nodejs
          - golden-path
 
    - id: register
      name: Backstage 카탈로그 등록
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml
 
  outputs:
    - id: repository
      title: GitHub 저장소
      url: ${{ steps.publish.output.remoteUrl }}

# skeleton/.github/workflows/ci.yaml
# 이 파일은 저장소 생성 즉시 활성화됩니다
name: CI
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: latest
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
 
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trivy 보안 스캔
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          exit-code: '1'
          severity: 'CRITICAL,HIGH'

// packages/backend/src/plugins/scaffolder/actions/registerCmdb.ts
import { createTemplateAction } from '@backstage/plugin-scaffolder-node';
import { z } from 'zod';
 
export const createRegisterCmdbAction = (options: { cmdbApiUrl: string }) => {
  return createTemplateAction({
    id: 'internal:register-cmdb',
    description: '내부 CMDB에 서비스를 등록합니다',
    schema: {
      input: z.object({
        serviceName: z.string(),
        owner: z.string(),
        serviceType: z.enum(['backend', 'frontend', 'data-pipeline']),
      }),
      output: z.object({
        cmdbId: z.string(),
      }),
    },
    async handler(ctx) {
      const { serviceName, owner, serviceType } = ctx.input;
 
      ctx.logger.info(`CMDB에 ${serviceName} 등록 중...`);
 
      const response = await fetch(`${options.cmdbApiUrl}/services`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name: serviceName, owner, type: serviceType }),
      });
 
      if (!response.ok) {
        throw new Error(`CMDB 등록 실패: ${response.status} ${response.statusText}`);
      }
 
      const { id } = await response.json();
      ctx.output('cmdbId', id);
      ctx.logger.info(`CMDB 등록 완료: ${id}`);
    },
  });
};

steps:
  - id: cmdb
    name: 내부 CMDB 등록
    action: internal:register-cmdb
    input:
      serviceName: ${{ parameters.name }}
      owner: ${{ parameters.owner }}
      serviceType: backend
 
  - id: notify
    name: Slack 알림 발송
    action: internal:notify-slack
    input:
      channel: '#platform-updates'
      message: |
        새 서비스가 생성되었습니다: *${{ parameters.name }}*
        소유 팀: ${{ parameters.owner }}
        저장소: ${{ steps.publish.output.remoteUrl }}
        CMDB ID: ${{ steps.cmdb.output.cmdbId }}

# skeleton/infra/database.yaml (Crossplane XRD 클레임)
# Nunjucks 조건문으로 enableDatabase가 true일 때만 파일이 생성됩니다
{% if values.enableDatabase %}
apiVersion: database.myorg.io/v1alpha1
kind: PostgreSQLInstance
metadata:
  name: {{ values.name }}-db
  namespace: {{ values.name }}
spec:
  parameters:
    storageGB: 20
    version: "15"
  writeConnectionSecretToRef:
    name: {{ values.name }}-db-secret
{% endif %}

# skeleton/argocd/app.yaml
# App of Apps 패턴: 루트 ArgoCD 앱이 이 파일을 감지해 새 Application을 등록합니다
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: {{ values.name }}
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/{{ values.name }}
    targetRevision: HEAD
    path: helm
  destination:
    server: https://kubernetes.default.svc
    namespace: {{ values.name }}
  syncPolicy:
    automated:
      prune: true
      selfHeal: true