TechDocs 아키텍처
Backstage를 배포하면(기본적으로 TechDocs가 활성화됨) 기본적인 out-of-the-box 경험을 얻을 수 있어요.
출처: 문서
본문
기본 구성(Basic, out-of-the-box)
Backstage를 배포하면(기본적으로 TechDocs가 활성화됨) 기본적인 out-of-the-box 경험을 얻을 수 있어요.
note
안정성, 확장성, 속도를 처리해 주는 권장 배포 아키텍처는 아래를 참고하세요. HOW TO 마이그레이션 가이드도 함께 보세요.
Backstage에서 TechDocs 사이트를 열면 TechDocs Reader가 techdocs-backend 플러그인에 엔티티 ID와 현재 보고 있는 페이지의 경로를 담아 요청을 보내요. 응답으로 페이지를 TechDocs/Backstage에서 렌더링할 정적 파일(HTML, CSS, JSON 등)을 받아요.
정적 파일은 MkDocs가 생성한 HTML, CSS, 이미지로 구성돼요. 보안상 이유로 Backstage에 추가하기 전에 JavaScript를 모두 제거해요. 그리고 TechDocs가 사이트를 렌더링하는 데 필요한 추가 techdocs_metadata.json 파일이 있어요. 기대한 출력물을 만들려면 techdocs-cli나 techdocs-container를 이용해 문서를 생성하는 것이 중요해요.
그다음 TechDocs Reader는 생성된 정적 HTML 파일을 여러 사용 사례에 맞게 수정하는 "Transformer" 목록(개념 참고)을 적용해요. 예를 들어 특정 헤더 제거, 일부 HTML 태그 필터링 등이죠.
현재는 생성된 파일을 백스테이지 서버(또는 techdocs-backend)의 로컬 파일 시스템에 저장해요. 하지만 외부 저장 시스템(예: AWS S3, GCS, Azure Blob Storage)을 쓰는 것이 이상적이에요. 자세한 내용은 클라우드 저장 사용하기에서 읽을 수 있어요.
권장 배포(Recommended deployment)
프로덕션 환경에서 TechDocs를 배포하는 것을 이렇게 권장해요.
권장 배포 방식의 핵심 차이는 문서가 어디서 빌드되느냐예요.
각 엔티티가 어딘가의 저장소(GitHub, GitLab 등)에 존재한다고 가정해요. 문서를 생성하는 전용 단계/작업이 있는 저장소와 함께 CI/CD 파이프라인을 사용할 것을 권장해요. 생성된 정적 파일은 그다음 선택한 클라우드 저장 솔루션에 저장돼요.
기본 구성에서처럼 TechDocs Reader는 techdocs-backend 플러그인에 문서 사이트를 요청해요. 그러면 techdocs-backend가 구성된 저장 솔루션에 필요한 파일을 요청하고, 그것을 TechDocs Reader에 반환해요.
선택한 클라우드 저장 제공자와 백엔드 서버의 실제 지리적 근접성에 따라, 이 배포 방식으로 TechDocs 사이트를 로드할 때 비교적 큰 대기 시간이 있을 수 있어요. 이 문제를 만나면 선택적으로 techdocs-backend가 Backstage가 지원하는 캐시 저장소에 응답을 캐시하도록 구성할 수 있어요.
보안 고려 사항
가장 큰 보안 우려는 클라우드 저장의 문서에 대한 접근을 관리하는 것이에요. 또한 서로 다른 유형의 저장(GCS, AWS, 커스텀 SFTP 서버 등)에 대해 단 하나의 보안 솔루션만 두고 싶어요. 저장에 대한 접근을 제한하고 techdocs-backend만 파일을 가져올 수 있게 하는 것이 이를 달성하는 좋은 방법이에요.
이렇게 하면 준비되면 Backstage의 접근 제어 관리를 사용할 수도 있어요. 진행 상황은 여기에서 추적하세요.
이론적으로는 TechDocs Reader가 저장에서 직접 읽도록 설정할 수도 있어요. 다만 문서가 공개되지 않도록 하는 방법과 사용자 그룹에 대한 접근을 어떻게 관리할지 생각해야 해요.
클라우드 저장 접근 토큰의 경우 techdocs-backend는 읽기 권한이 있는 토큰만 필요해요. 하지만 CI/CD 시스템에서는 생성된 문서 사이트 파일을 게시하기 위해 쓰기 권한이 있는 토큰이 필요해요.
자주 묻는 질문(FAQs)
Q: 왜 "기본"과 "권장" 배포 방식을 따로 두나요?
A: 기본 또는 out-of-the-box 구성은 새 앱을 만들거나 Backstage 저장소를 git clone할 때 얻는 것이에요. 첫 경험은 매끄러운 TechDocs 첫 경험을 할 수 있도록 마법처럼 동작하길 바래요. 하지만 Backstage/TechDocs를 프로덕션 용도로 배포하기로 결정하면, 기본 구성도 동작하지만 문서 사이트의 수와 크기가 커지며 확장할 때 단점이 생겨요. 그래서 배포를 가능한 한 안정적으로 만들고 싶을 거예요. 그래서 권장 방식이 있는 것이죠. TechDocs에는 더 많은 배포 방식이 있을 수 있고, 커뮤니티의 그러한 "대안" 아이디어를 환영해요.
Q: 왜 techdocs-backend 로컬 파일시스템으로 정적 파일을 서빙하는 것을 권장하지 않나요?
A: Backstage 인스턴스 확장을 더 어렵게 만들기 때문이에요. 분산된 Backstage 배포(예: Backstage 앱의 여러 Kubernetes 파드)를 생각해 보세요. TechDocs용 별도의/중앙 파일 저장 시스템을 쓰는 것은 서버/파드가 재시작될 때 사이트가 영속적이도록 하고 인스턴스별로 사이트를 중복하지 않기 위해 필요해요. 외부 저장을 두면 문서 사이트를 삭제하거나 내용을 지우는 같은 연산을 더 쉽게 할 수 있어요.
Q: 왜 사용자가 페이지를 방문할 때 실시간으로 문서를 즉석에서(on the fly) 빌드하지 않나요?
A: Markdown에서 콘텐츠를 즉석에서 생성하는 것은 최적이 아니에요. 저장 솔루션이 생성된 정적 콘텐츠의 캐시 역할을 해요. TechDocs는 현재 MkDocs 기반으로 구축되어 페이지별로 문서를 생성할 수 없어서, 요청마다 엔티티에 대한 모든 문서를 빌드해야 해요.
Q. techdocs-backend 플러그인 없이 techdocs 플러그인을 쓸 수 있나요?
A: techdocs와 techdocs-backend 플러그인은 다른 Backstage 플러그인이 프런트엔드와 그 백엔드(catalog, scaffolder 등)와 함께 쓰이듯이 함께 사용하도록 설계됐어요. Backstage 인스턴스가 서버에서 문서를 생성하도록 설정하면 techdocs-backend가 전체 빌드 과정을 관리하고 확장 가능하게 만드는 책임을져요. 정적 생성 사이트를 가져오는 것과 업데이트를 게시하는 것 모두, 클라우드 저장 제공자와 안전하게 통신하는 책임도 있어요. 사용자가 특정 문서 사이트를 볼 권한이 있는지 판단하는 인증 계층 같은 다른 계획된 기능도 있어요. 긴밀하게 통합된 백엔드가 없으면 개발하기 극도로 어려운 기능이 꽤 있죠. 그래서 techdocs-backend 없는 techdocs 지원은 제한적이고 개발하기 어려워요.