배포 골든 패스 문서 작성 가이드
이 문서는 문서 사이트에는 표시되지 않는 골든 패스 배포 가이드의 작성 지침이에요. 가이드를 새로 쓰거나 다듬을 때 참고하면 돼요.
출처: 문서
본문
용어집
- 페이지(Page): 하나의
md파일. - 가이드(Guide): 같은 폴더 아래에 묶인 여러 페이지.
전반적인 작성 지침
이 문서의 목표는 개발자와 관리자가 Backstage 인스턴스를 빠르게 프로덕션으로 올리고, 인스턴스가 성숙해감에 따라 계속 참고할 수 있는 포괄적인 가이드 세트를 제공하는 거예요.
이 가이드를 모두 마친 사용자는 프로덕션에서 Backstage 배포를 운영하는 데 자신감을 갖게 될 거예요. 여기에는 Docker 이미지 빌드, 배포 모니터링, Backstage 최신 상태 유지가 포함돼요.
동시에 모든 사용자가 문서를 끝까지 읽지는 않거나 필요할 때 다시 찾아볼 수도 있어요. 개별 가이드는 강력한 "개요(abstracts)"(이 가이드를 읽으면 무엇을 배우는지), 목차, 그리고 "다음 단계(next steps)"(다음에 무엇을 해야 하는지)를 갖춰 사용자가 작업에 가장 중요한 부분을 읽도록 안내해야 해요.
가이드 페이지를 쓸 때는 가볍게 유지하세요! 지시형 문서이면서도 대화체로 읽는 재미가 있어야 해요. 가이드는 서로를 이어가야 하며, 진행 단계를 따라 읽을 때 독자가 단계마다 등장하는 개념에 더 익숙해지고 자신감이 생겨야 해요. 가이드는 독립적이되 서로 링크할 수 있어야 해요.
섹션
사용자는 이미 Backstage 앱을 만들었다고 가정하지만, 무엇이든 커스터마이징했다고는 기대하지 않아요.
사전 준비
사용자는 이미 Backstage 앱(create-app)을 만들고 소스 코드를 소스 제어 관리 시스템(GitHub, GitLab 등)의 origin에 푸시했어야 해요. 또 회사가 코드를 어떻게 빌드하고 배포하는지 파악하고 있어야 해요.
Backstage 배포하기
Backstage는 회사의 다른 소프트웨어와 같은 방식으로 배포돼야 해요. Backstage를 처음 배포할 때나 배포 관행이 자리 잡지 않은 팀에 유용할 수 있는 흔한 예시를 보여주세요.
Docker
Docker 이미지에는 무엇이 들어있나요?
백엔드 이미지의 빌드 과정과 프론트엔드·백엔드를 이미지에 어떻게 겹겹이 쌓는지 설명해요.
CI에서 실행하기
이 빌드를 로컬에서 실행할 수도 있지만, 일반적으로는 CI 빌드의 일부로 실행할 거예요. 필요한 명령과 그것이 무엇을 하는지에 대한 맥락을 보여주세요.
배포 전 의존성
데이터베이스
SQLite는 Backstage 개발의 기본 데이터베이스예요. 개발자의 일상적인 요구를 감당할 수 있는 빠른 인메모리 데이터베이스지만, 프로덕션 용도에는 잘 맞지 않아요. 일반적으로는 전용 데이터베이스가 필요하죠.
이 섹션에서 데이터베이스 옵션을 살펴보고, Postgres가 일반적으로 가장 좋은 선택인 이유와 일반적인 제공자에 연결하는 데 필요한 설정을 설명해 주세요.
인증
기본적으로 Backstage는 사용자가 게스트 사용자로 로그인하게 해요. 로컬에서 탄탄한 개발자 경험을 제공하기엔 좋지만, 프로덕션에 배포하면 보안 구멍이 생길 수 있어요. 그래서 다른 인증 제공자를 설정해야 해요. 자세한 내용은 auth/* 문서를 참고하세요. 탄탄한 선택지는 GitHub 인증이에요. 개발자 포털의 대상 사용자라면 GitHub에 이미 접근 권한이 있을 테니까요.
배포 가이드
ECS
K8s
Other
저장소의 contrib/ 섹션을 참고하세요.
설정 우선 개발 (Config-first Development)
설정을 애플리케이션 동작에 영향을 주는 주요 수단으로 만들면 배포 과정이 단순해지고 Backstage 인스턴스 관리가 훨씬 수월해져요.
모니터링
OpenTelemetry
Backstage는 기본적으로 OpenTelemetry 메트릭 세트를 제공해요. 이 가이드에서는 이를 설정하는 방법, 무엇을 모니터링할지, 좋은 알람이 어떤 모습인지 안내할 거예요.
프론트엔드 분석
Backstage는 프론트엔드에서 사용자 동작을 추적하기 위해 Google Analytics 같은 다양한 벤더와 통합할 수 있는 프론트엔드 분석 API도 제공해요.
프론트엔드 오류 보고를 위해 CloudWatch RUM, Sentry 또는 Cloudflare RUM 같은 것과 통합하는 것을 고려해 보세요.
사용량이 늘어남에 따라 확장을 다루는 방법
pod 수를 늘리는 방식의 수평 확장이나, 비싼 특정 플러그인을 골라 자체 배포로 옮기는 방식에 대해 이야기해요.
프론트엔드와 백엔드 분리하기
기본적으로 프론트엔드는 @backstage/plugin-app-backend 플러그인을 사용해 여러분의 배포에서 서빙돼요. 프론트엔드를 분리해서 CDN에 배포해야 한다면 이 섹션에서 그 방법을 보여줄 거예요.