[k8s] Backstage 운영 후기: 개발자 포털 1년 회고와 정착 과정

목차

• Backstage란 무엇이고 왜 도입했나
• Backstage 도입 전에 먼저 정한 기준
• 1. 첫 3개월 목표는 검색성과 소유권 정리
• 2. 카탈로그 품질이 화면보다 먼저다
• 3. 운영팀이 다 입력하지 않는다
• Backstage 개발자 포털 구축: 첫 배포까지
• Backstage 운영 후기에서 편해진 지점: 카탈로그, 템플릿, 문서
• 카탈로그(Catalog, 서비스 자산 목록)
• 소프트웨어 템플릿(Software Templates, 표준 생성 템플릿)
• TechDocs(테크독스, 문서 자동 게시)
• 1년 운영하면서 겪은 문제들
• 1. 카탈로그 등록률이 생각보다 안 올라갑니다
• 2. 조직도와 실제 책임 구조가 다릅니다
• 3. 플러그인 욕심이 커집니다
• 4. 권한 관리가 늦어지면 나중에 더 아픕니다
• 검증: 무엇이 실제로 달라졌나
• Backstage 도입 사례로 정리하는 운영 팁
• 정리와 다음 단계
• 자주 묻는 질문
• Backstage는 작은 팀에도 필요할까요?
• 개발자 포털 구축에서 가장 먼저 해야 할 일은 뭔가요?
• 플랫폼 엔지니어링과 Backstage는 같은 말인가요?
• CNCF Backstage를 도입하면 문서 문제가 해결되나요?

Backstage 운영 후기: 개발자 포털 1년 회고와 정착 과정

Backstage 운영 후기를 정리해보려고 합니다. 개발팀이 커질수록 문서는 여기저기 흩어지고, 서비스는 늘어나고, 누구에게 뭘 물어봐야 하는지도 점점 모호해지더라고요. 저도 인프라 일을 오래 하면서 이런 상황을 정말 많이 봤습니다. 처음엔 위키만 잘 정리하면 되겠지 싶었는데, 실제로 써보니 위키만으로는 서비스 카탈로그(Service Catalog, 서비스 목록 체계), 템플릿(Template, 표준 생성 양식), 권한 관리(Permission, 접근 제어)까지 한 번에 풀기 어렵더라고요. 그래서 선택한 게 바로 Backstage였습니다.

이 글은 화려한 성공담보다는, 실제에 가까운 Backstage 도입 사례 기록입니다. 도입 검토부터 초기 구축, 팀 정착, 그리고 1년 운영하면서 느낀 한계까지 솔직하게 적어보겠습니다. 지금 개발자 포털 구축을 고민 중이라면 시행착오를 줄이는 데 도움이 될 겁니다.

Backstage를 중심으로 Git 저장소, CI/CD, 문서, 모니터링 도구가 연결되는 전체 구조를 한눈에 보여주는 이미지입니다.

Backstage란 무엇이고 왜 도입했나

쉽게 말해 Backstage는 개발자 포털을 구축할 때 쓰는 오픈소스 프레임워크입니다. 서비스 목록을 모아두는 화면이기도 하고, 팀 표준을 배포하는 플랫폼이기도 하고, 신규 서비스 생성 흐름을 자동화하는 입구이기도 하죠. 처음엔 “이거 그냥 내부 위키랑 뭐가 다르지?” 싶었는데, 막상 운영해보니 차이가 꽤 컸습니다.

제가 체감한 가장 큰 차이는 세 가지였습니다.

• 서비스를 문서가 아니라 엔티티(Entity, 관리 대상 객체)로 다룬다: 팀, 시스템, API, 컴포넌트를 관계로 연결할 수 있습니다.
• 소유권(Ownership, 담당 주체)이 드러난다: 장애가 났을 때 누가 관리하는지 찾는 시간이 줄었습니다.
• 표준화가 강제된다: 새 저장소를 만들 때부터 템플릿으로 기본 구조를 맞출 수 있거든요.

특히 플랫폼 엔지니어링(Platform Engineering, 개발 생산성 플랫폼 설계) 관점에서 좋았던 건, 운영팀이 “지침”만 주는 게 아니라 “실행 가능한 기본값”을 제공할 수 있다는 점이었습니다. 말로만 표준을 외치면 잘 안 지켜집니다. 그런데 템플릿에 녹여두면 생각보다 잘 따라오더라고요. 이거 진짜 편했습니다.

참고로 Backstage는 CNCF 인큐베이팅 프로젝트이기도 합니다. 그래서 CNCF Backstage라는 표현을 쓰더라도, 제품명이라기보다 CNCF 생태계에 속한 Backstage를 가리키는 말로 이해하는 편이 자연스럽습니다.

Backstage 도입 전에 먼저 정한 기준

Backstage는 기능이 많지만, 처음부터 다 하려 들면 거의 반드시 무너집니다. 저도 처음엔 카탈로그, 문서, 템플릿, 플러그인(Plugin, 확장 기능), 권한까지 한 번에 붙이려다가 시행착오를 꽤 겪었습니다. 그래서 기준을 다시 잡았습니다.

1. 첫 3개월 목표는 검색성과 소유권 정리

처음부터 모든 자동화를 노리진 않았습니다. 가장 먼저 해결한 건 “우리 서비스가 몇 개인지”, “이 서비스 담당 팀이 누구인지”, “배포 파이프라인이 어디 있는지”를 한 화면에서 보이게 하는 것이었습니다.

2. 카탈로그 품질이 화면보다 먼저다

Backstage는 화면보다 데이터가 중요합니다. <code>catalog-info.yaml이 엉망이면 나중에 검색도, 관계도, 문서 연결도 다 지저분해집니다. 그래서 초기에 메타데이터 규칙부터 정했습니다.

3. 운영팀이 다 입력하지 않는다

플랫폼은 중앙집중형으로 굴리면 오래 못 갑니다. 각 팀이 자기 서비스 메타데이터를 유지하게 하고, 운영팀은 템플릿과 검증 규칙을 관리하는 식으로 분리했습니다.

항목	초기 목표	1년 뒤 목표
서비스 카탈로그	핵심 서비스 등록	전 팀 기본 등록
소유권 표시	팀 단위 매핑	온콜/문서 링크까지 연결
소프트웨어 템플릿	1~2개 표준 템플릿	언어/런타임별 확장
TechDocs	중요 서비스만	문서 작성 습관 정착
권한 관리	최소 권한	팀/역할 기반 세분화

Backstage 개발자 포털 구축: 첫 배포까지

개발자 포털 구축 자체는 생각보다 빨리 됩니다. 문제는 그 다음부터입니다. 기본 앱을 만들고, 로컬에서 띄우고, 카탈로그 엔티티를 등록해보는 것까지는 공식 흐름이 꽤 잘 되어 있습니다.

1. 새 Backstage 앱 생성
2. 기본 실행 확인
3. 카탈로그 엔티티 등록
4. 인증과 조직 구조 연결
5. 템플릿과 문서 기능 추가

저는 초기에 아주 단순한 구조로 시작했습니다. 로컬에서 먼저 확인하고, 이후 컨테이너(Container, 실행 격리 환경)로 배포하는 흐름이었습니다. 현재 공식 시작 가이드 기준으로는 아래처럼 앱을 만든 뒤 yarn start로 프런트엔드와 백엔드를 함께 띄우는 방식이 가장 기본입니다.

npx @backstage/create-app@latest
cd my-backstage-app
yarn install
yarn start

처음 화면이 뜨면 “생각보다 금방 되네?” 싶습니다. 그런데 여기서 중요한 포인트가 있습니다. 로컬 실행 성공은 시작일 뿐입니다. 실제 운영에서 중요한 건 인증, 카탈로그 입력 규칙, 저장소 구조, 문서 관리 방식입니다.

서비스 등록은 아래처럼 아주 기본적인 엔티티 파일부터 시작했습니다.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api
  description: Payment service for internal platform
  tags:
    - backend
    - critical
spec:
  type: service
  lifecycle: production
  owner: team-platform
  system: commerce-platform

이 단계에서 중요한 건 멋진 화면이 아니라 명명 규칙(Naming Convention, 이름 규칙)입니다. 이름이 제각각이면 검색이 바로 망가집니다. 실제로 써보니까 team-, svc- 같은 접두사(prefix, 앞부분 식별자)를 과하게 쓰는 것도 오히려 헷갈리더라고요. 적당히 단순해야 오래 갑니다.

Component, API, System, Group 엔티티가 서로 연결된 카탈로그 구조를 보여주는 이미지입니다.

Backstage 운영 후기에서 편해진 지점: 카탈로그, 템플릿, 문서

카탈로그(Catalog, 서비스 자산 목록)

Backstage 운영 후기에서 빼놓기 어려운 핵심은 카탈로그입니다. 저는 처음에 이걸 “서비스 목록 화면” 정도로 생각했었는데, 1년 써보니 사실상 운영 기준점이더라고요. 서비스가 장애를 냈을 때 저장소와 문서, 대시보드, 소유 팀을 한 번에 찾을 수 있다는 게 큽니다.

소프트웨어 템플릿(Software Templates, 표준 생성 템플릿)

이 기능은 팀 표준을 퍼뜨릴 때 정말 강력했습니다. 신규 서비스 생성 시 README, 기본 디렉터리 구조, CI 설정, 카탈로그 파일까지 자동으로 넣어주게 만들면 편차가 많이 줄어듭니다.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: simple-service-template
  title: Simple Service Template
spec:
  owner: team-platform
  type: service
  parameters:
    - title: Service Info
      required:
        - name
        - owner
      properties:
        name:
          type: string
          title: Service Name
        owner:
          type: string
          title: Owner Team
  steps:
    - id: fetch-base
      name: Fetch Base
      action: fetch:template
      input:
        url: ./template
        values:
          name: ${{ parameters.name }}
          owner: ${{ parameters.owner }}

처음엔 템플릿을 많이 만들수록 좋다고 생각했는데, 오히려 반대였습니다. 템플릿 종류가 많아지면 사용자가 뭘 선택해야 하는지 모르거든요. 그래서 1년 운영 후 기준은 명확해졌습니다. “가장 많이 쓰는 패턴부터 적게 만든다.” 이게 맞았습니다.

TechDocs(테크독스, 문서 자동 게시)

문서도 생각보다 영향이 컸습니다. 개발자 포털 구축에서 문서가 분리되어 있으면 결국 다시 검색 지옥으로 돌아갑니다. Backstage 안에서 문서가 보이게 만들면 적어도 “어디에 있는지”를 찾는 시간은 줄어듭니다. 다만 문서 품질 자체는 도구가 해결해주지 않습니다. 이건 운영 문화의 문제더라고요.

1년 운영하면서 겪은 문제들

여기부터가 진짜 운영 후기입니다. 설치보다 운영이 훨씬 어렵습니다.

1. 카탈로그 등록률이 생각보다 안 올라갑니다

플랫폼팀이 좋다고 생각하는 것과 현업팀이 귀찮다고 느끼는 건 늘 다릅니다. 특히 초기에는 “왜 이걸 또 적어야 하죠?”라는 반응이 있었습니다. 저도 처음엔 안내 문서를 길게 써놨었는데, 효과가 크지 않더라고요.

해결은 단순했습니다.

• 템플릿 생성 시 catalog-info.yaml 자동 포함
• 필수 필드 최소화
• 리뷰 체크리스트에 소유권 항목 추가
• 등록 안 된 서비스는 운영 지표에서 제외

강제와 편의의 균형이 중요합니다. 너무 세게 밀면 반감이 생기고, 너무 느슨하면 아무도 안 합니다.

2. 조직도와 실제 책임 구조가 다릅니다

Group(그룹, 팀 조직 엔티티)를 예쁘게 모델링해도 현실은 늘 예외가 있습니다. 명목상 팀과 실제 운영 담당이 다를 때가 있거든요. 그래서 저는 조직도 그대로만 넣지 않고, 서비스 기준 소유권을 별도로 정리했습니다. 여기서 중요한 건 HR 기준이 아니라 장애 대응 기준입니다.

3. 플러그인 욕심이 커집니다

Backstage는 플러그인이 많고 확장성이 좋아서, 운영하다 보면 이것저것 붙이고 싶어집니다. 그런데 여기서 많이 흔들립니다. 저도 한동안 대시보드, 품질 지표, 배포 이력, API 문서, 비용 정보까지 한 화면에 다 넣어보려 했는데요. 결과적으로는 정보 밀도가 너무 높아져서 오히려 안 보게 되더라고요.

정말 자주 보는 정보만 전면에 두고, 나머지는 링크로 넘기는 구조가 오래 갑니다.

4. 권한 관리가 늦어지면 나중에 더 아픕니다

초기엔 내부 도구니까 대충 열어두자 싶을 수 있습니다. 저도 솔직히 그랬습니다. 그런데 문서, 운영 대시보드, 템플릿 액션이 늘어나면 접근 제어가 갑자기 중요해집니다. 특히 프로덕션 관련 링크나 자동화 액션이 연결되기 시작하면 더 그렇습니다.

backend:
  auth:
    keys:
      - secret: ${BACKEND_SECRET}
permission:
  enabled: true

다만 실제 운영에서는 설정만 넣는다고 끝나지 않습니다. 현재 공식 문서 기준으로는 app-config.yaml의 permission.enabled: true 설정과 함께, 백엔드에 permission policy를 연결하는 작업이 같이 필요합니다. 여기서는 방향만 보여드리는 예시로 봐주시면 됩니다.

SSO 로그인 이후 템플릿 실행, 저장소 생성, 카탈로그 등록으로 이어지는 운영 자동화 흐름을 보여주는 이미지입니다.

검증: 무엇이 실제로 달라졌나

정량 지표를 과하게 꾸미고 싶진 않습니다. 다만 1년 운영하면서 체감 변화는 분명했습니다.

• 신규 입사자 온보딩 시 서비스 위치 파악이 빨라졌습니다.
• 운영 중 “이 서비스 누가 보나요?”라는 질문이 줄었습니다.
• 표준 저장소 구조가 어느 정도 정착됐습니다.
• 문서 링크와 대시보드 링크를 찾는 시간이 줄었습니다.

특히 장애 대응 때 차이가 컸습니다. 예전에는 메신저 검색부터 했거든요. 이제는 포털에서 서비스를 보고, 담당 팀을 보고, 관련 문서와 대시보드로 넘어가는 흐름이 꽤 자연스러워졌습니다. 이럴 때는 “아, 이거 도입하길 잘했네” 싶더라고요.

반대로 기대보다 덜 바뀐 것도 있습니다.

• 문서 최신화는 도구만으로 해결되지 않았습니다.
• 카탈로그 품질은 각 팀의 습관에 크게 좌우됐습니다.
• 포털 접속 빈도는 팀마다 차이가 컸습니다.

그래서 CNCF Backstage를 만능 해결책으로 보면 실망할 수 있습니다. 이건 포털 소프트웨어이면서 동시에 운영 문화 도구입니다. 플랫폼 엔지니어링의 일부이지, 전부는 아니더라고요.

서비스 소유권 가시성, 온보딩 속도 개선, 문서 연결 상태 등을 대시보드 형태로 요약한 이미지입니다.

Backstage 도입 사례로 정리하는 운영 팁

중요한 포인트만 추리면 이렇습니다.

1. 카탈로그부터 시작하세요. 검색성과 소유권이 먼저입니다.
2. 템플릿은 적게 만드세요. 제일 많이 쓰는 패턴 한두 개가 효과적입니다.
3. 문서 품질 책임은 각 팀에 남겨두세요. 플랫폼팀이 대신 다 맡기는 어렵습니다.
4. 권한 모델을 초기에 잡으세요. 뒤늦게 손보면 연결 범위가 너무 넓어집니다.
5. 플러그인은 신중하게 늘리세요. 첫 화면은 단순해야 계속 보게 됩니다.

상황	추천 접근	피해야 할 접근
초기 도입	카탈로그 중심 MVP	모든 기능 동시 도입
템플릿 설계	반복 패턴 우선	팀별 전용 템플릿 난립
문서 운영	작성 책임 분산	플랫폼팀 단독 관리
권한 관리	초기 정책 정의	운영 후반 일괄 정리
플러그인 확장	핵심 정보만 노출	한 화면에 모든 정보 집약

정리와 다음 단계

Backstage 운영 후기를 한 줄로 줄이면 이렇습니다. “설치는 빠른데, 정착은 결국 운영 설계의 문제다.” 저도 처음엔 도구만 잘 깔면 해결될 줄 알았는데, 실제로 써보니 카탈로그 품질, 조직 책임, 템플릿 설계, 권한 정책 같은 기본기가 훨씬 중요했습니다.

Backstage 도입 사례를 찾고 있다면 너무 크게 시작하지 않는 편이 낫습니다. 개발자 포털은 예쁜 화면이 아니라 팀의 작업 흐름을 바꾸는 도구입니다. 그래서 작게 시작해서, 자주 쓰는 흐름부터 붙이는 쪽이 훨씬 잘 되더라고요. 이전 글에서 다룬 홈랩 기반 GitOps 실험도 함께 읽어보시면 도입 배경을 더 자연스럽게 이어서 보실 수 있습니다.

다음 글에서는 TechDocs 운영 방식이나 소프트웨어 템플릿 표준화 전략을 더 깊게 다뤄볼 예정입니다.

도입 전후 차이, 추천 시작 순서, 운영 시 주의할 점을 한 장으로 정리한 요약 인포그래픽입니다.

자주 묻는 질문

Backstage는 작은 팀에도 필요할까요?

작은 팀이라면 반드시 필요하다고 보긴 어렵습니다. 다만 서비스 수가 늘고, 팀이 분화되고, 온보딩 비용이 커지기 시작하면 가치가 확실히 보입니다.

개발자 포털 구축에서 가장 먼저 해야 할 일은 뭔가요?

서비스 목록과 소유권 정리입니다. 화려한 자동화보다 먼저, 누가 어떤 서비스를 책임지는지 보여야 합니다.

플랫폼 엔지니어링과 Backstage는 같은 말인가요?

같지는 않습니다. Backstage는 플랫폼 엔지니어링을 구현할 때 쓰는 여러 도구 중 하나에 가깝습니다. 운영 방식과 조직 합의가 더 중요합니다.

CNCF Backstage를 도입하면 문서 문제가 해결되나요?

문서 위치 문제는 꽤 좋아집니다. 다만 문서 최신화 문제까지 자동으로 해결되진 않습니다. 그건 팀 습관과 리뷰 문화가 같이 따라와야 합니다.

📚 함께 읽으면 좋은 글

• Pod Security Standards 마이그레이션: Kubernetes PSP에서 안전하게 전환하기
• Karpenter 오토스케일로 EKS 비용 절감 검증하는 방법
• MicroK8s 벤치마크: K3s와 엣지 환경 성능 비교 [실전 가이드]