🏗️ 거버넌스와 자동화를 한 번에! Backstage 표준 스캐폴더(Template) 완벽 가이드

안녕하세요! 오늘은 플랫폼 엔지니어링의 핵심, Backstage 스캐폴더(Scaffolder)를 활용해 어떻게 "보안 가드레일이 포함된 표준 프로젝트"를 찍어낼 수 있는지 알아보겠습니다.

단순히 "코드를 복사"하는 것이 아니라, 누가, 어떤 목적으로, 어떤 보안 정책을 준수하며 생성하는지를 코드로 관리하는 방법을 공유합니다. 🛠️

---

1. 템플릿의 전체 구조 (Anatomy of a Template) 🦴

Backstage 템플릿은 크게 Metadata(이름, 설명), Parameters(사용자 입력), Steps(실행 단계), Output(결과 안내)으로 나뉩니다.

YAML

# 1. 템플릿의 신원 정의
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: standard-python-service
  title: "🛡️ 보안 표준 Python Flask 서비스"
  description: "KISA 보안 가이드라인과 CI/CD 스캔이 내장된 표준 API 서버를 생성합니다."
  tags: [standard, security, python]

spec:
  owner: platform-team
  type: service

  # 2. 사용자로부터 입력받을 '질문지'
  parameters:
    - title: "기본 정보"
      required: [component_id, owner]
      properties:
        component_id:
          title: "서비스 이름"
          type: string
          description: "생성할 프로젝트의 이름 (영문/숫자/-)"
        owner:
          title: "담당 팀"
          type: string
          ui:field: OwnerPicker # 백스테이지 등록 그룹 선택

    - title: "저장소 설정"
      required: [repoUrl]
      properties:
        repoUrl:
          title: "GitHub 위치"
          type: string
          ui:field: RepoUrlPicker # 저장소 생성 위치 선택
          ui:options:
            allowedHosts: [github.com]

  # 3. 실제 마법이 일어나는 '자동화 공정'
  steps:
    - id: fetch-base
      name: "표준 스켈레톤 가져오기"
      action: fetch:template
      input:
        url: ./skeleton # 템플릿 소스 폴더
        values:
          name: ${{ parameters.component_id }}
          owner: ${{ parameters.owner }}

    - id: publish
      name: "GitHub 저장소 생성 및 푸시"
      action: publish:github
      input:
        allowedHosts: ['github.com']
        description: "Created by Backstage Scaffolder"
        repoUrl: ${{ parameters.repoUrl }}

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

  # 4. 완료 후 사용자에게 보여줄 결과
  output:
    links:
      - title: "생성된 GitHub 저장소 보기"
        url: ${{ steps['publish'].output.remoteUrl }}

---

2. 핵심 단계별 코드 상세 설명 🔍

📍 Parameters: 데이터 입력의 기술

사용자가 입력하는 정보는 단순히 텍스트가 아닙니다. ui:field를 사용하면 백스테이지 시스템과 연동된 고도의 컴포넌트를 호출합니다.

• OwnerPicker: 조직도에 등록된 팀을 실시간으로 검색하여 선택합니다. 👥
• RepoUrlPicker: 권한이 있는 GitHub 조직을 골라 저장소 이름을 즉석에서 결정합니다.

📍 Steps: 자동화의 핵심 엔진

• fetch:template: 가장 중요한 단계입니다. ./skeleton 폴더에 있는 파일들을 복사하면서, ${{ values.name }} 같은 변수들을 실제 사용자가 입력한 값으로 '치환'합니다.
• publish:github: 단순히 코드를 올리는 게 아니라, GitHub API를 통해 저장소를 새로 생성하고 초기 커밋을 날립니다. 🛰️
• catalog:register: 생성된 서비스가 즉시 백스테이지 관리 목록(Catalog)에 나타나게 하여 "그림자 IT"를 방지합니다.

---

3. 프로젝트의 심장: Skeleton 폴더 🦴

템플릿이 참조하는 ./skeleton 폴더 안에는 무엇이 들어있을까요? 바로 표준 명세서입니다.

./skeleton/catalog-info.yaml (예시) 이 파일은 프로젝트가 생성되는 즉시 함께 생성되어, 서비스의 '신분증' 역할을 합니다.

YAML

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name | dump }}
  description: "이 서비스는 표준 템플릿으로 자동 생성되었습니다."
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner | dump }} # 생성 시 입력한 팀이 소유자로 자동 지정!

Tip: 여기서 ${{ values.owner }}를 사용함으로써, 생성과 동시에 소유권 관리가 자동으로 이루어집니다. 🛡️

---

4. 이 청사진이 가져다주는 결과 🎁

이 템플릿을 실행하면 개발자는 다음의 결과물을 1분 안에 얻게 됩니다.

1. GitHub 저장소: 표준 코드 구조와 CI/CD(GitHub Actions) 설정이 완료된 레포지토리. 📁
2. 보안 설정: 기본적으로 Trivy나 Snyk 같은 보안 스캔 설정이 포함된 상태로 시작. 🔒
3. 관리 자동화: 백스테이지 카탈로그에 등록되어 의존성 그래프와 문서(TechDocs)를 즉시 확인 가능. 📡

---

🔥 마치며: 왜 코드로 관리해야 하는가?

개발자가 직접 catalog-info.yaml을 작성하고 GitHub 설정을 만지면 오타가 나거나 보안 설정을 누락하기 쉽습니다. 하지만 Scaffolder 청사진을 통하면 "조직의 표준 정책"이 곧 "프로젝트의 시작점"이 됩니다.

이제 이 코드를 여러분의 백스테이지에 적용해 보세요! 여러분의 플랫폼 엔지니어링 여정이 한층 더 견고해질 것입니다. 🚀

---